安装 Appaloft

目标

在自己的服务器上安装并运行一份完整的 Appaloft 实例(包含 Web 控制台和公共文档)。

适用场景

需要完全掌控数据归属,不希望使用托管的 Appaloft Cloud。
在内网或无公网访问的环境中部署 Appaloft。

前置条件

一台可以运行 Docker 的 Linux 服务器(推荐),或者已下载对应平台的二进制包。
如果要绑定域名,需要提前把 DNS 指向这台服务器,并开放 80/443 端口。

输入与默认值

appaloft serve 的根路径提供 Web 控制台,/docs/* 提供公共文档——二进制包同时内嵌这两部分的静态资源,单机离线环境也能打开帮助文档。

CLI 操作步骤

最简安装(推荐)

curl -fsSL https://appaloft.com/install.sh | sudo sh

install.sh 会把 Appaloft 安装成一套 Docker Compose Stack,默认使用 PostgreSQL,适合生产自托管。

使用嵌入式数据库(单机场景)

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --database pglite

单机便携控制台可以继续使用嵌入式 PGlite;这种模式下 Appaloft 状态保存在挂载到 /appaloft-data 的持久 Docker Volume 中。

绑定域名

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --domain console.example.com

没有配置域名时,控制台可以通过服务器的 3721 端口访问。这个域名是 Appaloft 实例自己的控制台入口,不是项目资源的自定义域名,也不会创建部署快照或域名绑定。只有在外部反向代理已经负责公开入口时,才使用 --proxy none。

离线 / 内网安装

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --image <registry>/appaloft:<tag> --skip-image-pull

--image 用于指定预加载的 Appaloft 镜像;只有镜像已经存在于本机 Docker daemon 时,才加 --skip-image-pull。

Docker Swarm

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --database pglite --orchestrator swarm --stack-name appaloft

只有明确希望安装器初始化单节点 Swarm manager 时,才加 --swarm-init。

预期输出与状态

安装脚本会在 Appaloft HTTP 服务启动前自动应用待执行的数据库迁移。安装完成后会打印控制台 URL;默认还会启动一个 Appaloft 自己管理的 Traefik 边缘代理。

安装器会为产品登录会话生成并复用一个稳定密钥,保存在安装目录的 .env 中——升级或修复时不要删除这个值,否则已有登录会话会全部失效。

验证

打开安装器打印的控制台 URL,确认页面正常加载;然后按照创建首个管理员账号完成初始账号创建和登录。

回滚 / 恢复

迁移失败时容器不会通过健康检查,安装器会报错并提示查看容器日志;修复数据库或镜像问题后,重新运行同一条安装命令即可(安装器是幂等的,会复用已有配置和数据卷)。

不要把数据库密码、GitHub Token、SSH Key 或部署身份值写进仓库配置——这些值应该放在主机环境变量、CI 密钥库,或安装后的 Appaloft 实例内部。

进阶:链路追踪

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --trace jaeger

安装器会启动一个 Jaeger all-in-one 容器,把 Appaloft 的 OTLP 端点指向内部 collector,并把追踪链接写回 Jaeger UI(默认绑定 127.0.0.1:16686)。如果 Jaeger 通过其他域名公开,需要把 APPALOFT_TRACE_LINK_BASE_URL 设为这个外部 URL,详见运行时配置参考。

进阶:临时公网访问

已安装的 Appaloft 可以为本机或私网 HTTP 源启动有时限的临时公网隧道(Cloudflare Quick Tunnel 或 ngrok),用于快速给外部访问者一个临时地址:

appaloft tunnel start --provider cloudflare-quick --origin http://127.0.0.1:3000 --duration-minutes 60
appaloft tunnel list
appaloft tunnel show <tunnelId>
appaloft tunnel revoke <tunnelId>

Provider 凭据只从对应 Provider 的环境变量读取(例如 ngrok 使用 NGROK_AUTHTOKEN),不会被持久化或在查询结果中回显。公共源地址、带凭据的 URL、非 HTTP scheme 会被直接拒绝。

目标