跳到主要内容
版本:0.4 · 当前版

安装程序参考

参考审阅日期:2026年10月11日
适用于:Excubius 0.4角色: 安装人员(Linux 管理员)
计划Free · Core · Pro · Enterprise部署自托管

安装程序 install.sh 在一台服务器上安装、升级、重新安装和卸载 Excubius。它以 root 身份从解压后的安装包中运行。本参考列出它的选项、预检查、它提出的问题以及它在服务器上留下的内容。安装步骤请参阅安装 Excubius。

sudo ./install.sh [options]

选项​

选项作用
(无)安装。在已安装 Excubius 的服务器上,提供 Upgrade(默认值:保留数据和设置,只询问此版本新增的问题)、Reinstall、Purge 或 Cancel
--check-only只运行预检查。不更改任何内容
--images FILE从映像存档安装,无需访问注册表。脚本旁边 images/ 中的存档(如离线包中那样)会自动使用
--answers FILE非交互式:key=value 行,包含机密。请参阅回答文件
--reconfigure升级时再次询问每个问题。此时给出的 TLS 回答会应用于运行中的平台
--reinstall删除已安装的软件但保留数据库,然后安装并询问每个问题
--purge删除所有内容(包括数据库),然后全新安装
--uninstall删除软件。先将最终的数据库转储写入 <dir>/backups/,然后删除用户单元、容器、映像、<dir>/releases、<dir>/current、/etc/excubius 和无根端口设置。保留数据库和证书卷、<dir>/backups、<dir>/.env 和服务账户,以便之后的安装能找到数据
--uninstall --purge同时删除所有卷、包含备份的整个安装目录、安装程序创建的服务账户及其容器存储,以及安装添加的防火墙服务。要求你键入 purge
--no-backup在 --uninstall 或 --reinstall 时不做最终的数据库转储
--yes、-y接受所有存在的默认值;必需的回答仍须来自 --answers 或键盘。在已安装的服务器上表示 Upgrade,并确认清除
--dry-run打印将要执行的操作,不更改任何内容。安装仍会写入其配置文件供你审阅;若已有 .env,则写为它旁边的 .env.dry-run
--skip-checks即使预检查失败也继续,适用于不受支持的系统,风险自负
--help、-h打印选项

以下组合会被拒绝:--uninstall 与 --reinstall 或 --reconfigure;--purge 与 --reinstall;--check-only 与 --uninstall、--purge 或 --reinstall;--reconfigure 与 --purge 或 --reinstall。

只会删除已记录的安装目录,绝不会删除系统路径或主目录。

预检查​

检查要求不满足时
操作系统Rocky Linux 或其他 RHEL 系列系统失败
主要版本9 或 10警告
体系结构x86-64失败
初始化系统systemd失败
包管理器dnf失败
内存4 GiB警告
CPU2 个 vCPU警告
磁盘/home 下有 20 GiB 可用空间,服务账户在那里保存映像和数据库警告
端口新安装时 80 和 443 端口空闲失败
SELinux报告状态—
注册表可通过 HTTPS 访问 ghcr.io 和 docker.io,或有可读取的映像存档失败
时钟已同步警告;会启用 chrony

问题​

按 Enter 接受括号中的值。升级时,只会询问在写入你的回答的版本之后新增的问题;引入版本列说明每个问题由哪个版本引入。

键问题默认值询问时机引入版本
install_dir安装目录/opt/excubius始终询问;绝对路径0.2.0
service_user运行平台的服务账户excubius始终询问;缺失时创建,以无根方式运行容器0.2.0
public_url用户将打开的公共 URLhttps://monitoring.example.com始终询问;其主机部分是服务器的主要名称0.2.0
server_aliases此服务器的其他名称无始终询问;以空格分隔,没有则直接按 Enter0.3.0
tls_mode如何提供 HTTPSletsencrypt始终询问:letsencrypt、letsencrypt-dns、selfsigned、custom、gateway 或 later0.2.0
tls_cert_names要放入证书的名称all存在别名,并且该模式会生成证书0.3.0
tls_emailLet's Encrypt 账户的电子邮件地址—letsencrypt 或 letsencrypt-dns0.2.0
tls_dns_provider名称所在区域的 DNS 提供商—letsencrypt-dns;acme.sh dnsapi ID,例如 dns_cf、dns_dreamhost 或 dns_azure0.3.0
tls_dns_credentialsDNS API 凭据—letsencrypt-dns;逐个输入,不回显0.3.0
tls_cert_file证书链文件—custom;PEM,服务器证书在前0.3.0
tls_key_file私钥文件—custom;PEM,无密码短语,与证书匹配0.3.0
default_preset基础预设enterprise始终询问:enterprise、databases 或 core0.2.0
registry_user、registry_token映像的注册表用户和只读令牌—没有映像存档时0.2.0
slack_bot_tokenSlack 机器人令牌—始终询问;可选0.2.0
slack_default_channel警报所用的 Slack 频道#alerts始终询问0.2.0
entra_tenant_id登录所用的 Entra ID 租户 ID—始终询问;可选0.2.0
entra_client_id、entra_client_secretEntra ID 应用程序 ID 和客户端机密—已提供租户 ID0.2.0

TLS 模式:

模式适用情形
letsencrypt每个名称都在公共 DNS 中指向该服务器,并且 80 端口可从 Internet 访问
letsencrypt-dns你拥有名称所在 DNS 区域的 API 凭据。服务器无需能从 Internet 访问
selfsigned任何位置。在用户信任该证书之前,浏览器会显示警告
custom由你的组织颁发证书
gatewayTLS 在前端的负载均衡器或反向代理上终止
later暂时使用纯 HTTP

使用 Let's Encrypt 模式时,安装程序会在公共 DNS 中检查这些名称,并通过 HTTP 检查它们是否指向这台服务器。如果没有指向,它会说明可选的替代方案,但不会因此停止。TLS 回答只用于初始化平台的设置;之后在 Settings › Server 中管理。

生成的值​

安装程序会一次性生成这些值,并且从不覆盖它们:数据库密码(POSTGRES_PASSWORD)、会话签名机密(JWT_SECRET)、加密所存储机密的密钥(EXCUBIUS_DATA_KEY)和采集器令牌(EXCUBIUS_COLLECTOR_TOKEN)。请参阅环境变量。

回答文件​

若要无人参与安装,请使用 --answers FILE 传入一个文件,其中每个问题占一行 key=value。此文件包含机密;请保护好它,并在用完后删除。DNS 凭据放在同一行,以 ; 分隔。缺少的回答采用默认值;缺少或无效的必需回答会使安装程序停止,并给出键的名称,因此你可以补全文件后再次运行。

节选:

install_dir=/opt/excubius
service_user=excubius
public_url=https://monitoring.areito.example
server_aliases=
tls_mode=letsencrypt-dns
tls_email=ops@areito.example
tls_dns_provider=dns_cf
tls_dns_credentials=CF_Token=<token>
default_preset=enterprise
registry_user=<registry user>
registry_token=<read-only token>
slack_bot_token=<bot token>
slack_default_channel=#areito-alerts
sudo ./install.sh --answers ./answers.conf --yes

升级和带版本的回答​

安装程序将你的非机密回答记录在 <dir>/install.answers 中,同时记录写入这些回答的安装程序版本,以及该次运行是否已完成。升级时,它只询问自该版本以来新增的问题。未完成的运行会被视为新的安装:每个问题都会再次询问,并以先前的回答作为默认值。机密从不会写入 install.answers。

服务器上的内容​

路径内容
<dir>/.env配置和机密;权限模式 0600,归服务账户所有
<dir>/install.answers你的非机密回答、写入这些回答的版本,以及该次运行是否已完成
<dir>/current已安装的版本,一个指向 <dir>/releases/ 的链接
<dir>/backups每日数据库转储,保留最近 14 份,外加卸载时的最终转储
~<service account>/.config/systemd/user/excubius.service 和备份计时器
/var/log/excubius-install.log安装程序的日志,不含机密

以服务账户身份:

sudo -iu excubius
export XDG_RUNTIME_DIR=/run/user/$(id -u) # once per shell, for systemctl --user
systemctl --user status excubius # the platform
<dir>/current/scripts/compose.sh ps # the containers
<dir>/current/scripts/compose.sh logs -f backend # the API's log
<dir>/current/scripts/backup-db.sh # a database backup now
<dir>/current/scripts/enable-tls.sh --status # TLS without the console
<dir>/current/scripts/rollback.sh # back to the previous release