自托管

在一台 Linux 主机上，以有 sudo 权限的用户执行：

curl -fsSL https://acahti.dev/install.sh | bash -s -- --domain acahti.example.com

脚本会在缺少 Docker 时自动安装，从 ghcr.io/acahti-ai/acahti 拉取发布镜像，把 compose 文件和主机脚本复制到 ~/acahti，生成密钥写入 ~/acahti/.env，然后启动实例。主机上不进行任何构建。

也可以交给你的编程 Agent 来做：

Install https://acahti.dev/install.md
Self-host Acahti on my infrastructure. Ask me for the domain, SSH access, and Runner host.

准备工作#

• 一台有 sudo 权限、内存至少 2 GiB 的 Linux 主机。
• 一个公网 HTTPS 域名。TLS 在你自己的反向代理或隧道上终止，再转发到网关。
• 可选：再准备一台主机作为「执行节点」，第一台主机要能通过 SSH 访问它。CI 永远不在控制平面上运行。

选项#

选项会写入 .env，后续运行时沿用。数据存放在 ACAHTI_DATA 下（默认 /var/lib/acahti）。

安装之后#

1. 把代理或隧道指向网关，然后打开实例 URL。
2. 在 Web 应用中邀请成员。每个人通过 <instance>/join 加入。
3. 把实例首页上的 Agent 提示词粘贴给编程 Agent，打开「看板」，看它跑完演示流程。

升级#

先备份 PostgreSQL 和 ACAHTI_DATA，再重新运行安装脚本：

curl -fsSL https://acahti.dev/install.sh | bash

它会安装最新版本，保留 .env 和数据，并重新同步执行节点。用 --version 可以固定版本。早于 0.15.0 的实例先升级到 0.15.2，再升级到最新版本。不要在运行中的实例上执行 docker compose down -v。

发布交付#

网关、MinIO、Caddy 边缘代理、Gotenberg、Tika 和 ONLYOFFICE Docs 是各自独立的镜像。MinIO 使用 ghcr.io/acahti-ai/acahti:minio-<MINIO_IMAGE_VERSION>，边缘代理使用 caddy:<CADDY_VERSION>-alpine，Gotenberg 使用 gotenberg/gotenberg:<GOTENBERG_VERSION> 生成 Office 预览，Tika 使用 apache/tika:<TIKA_VERSION> 从 PDF 和 Office 文件中提取可搜索文本，onlyoffice/documentserver:<ONLYOFFICE_VERSION> 用于在浏览器中编辑知识库文件。这些版本固定在 versions.env 中，应用版本发布时沿用。离线安装时，先加载全部六个镜像归档，再运行安装脚本。ONLYOFFICE 最多需要 3 GiB 内存，启动后还要一两分钟文档才能在编辑器中打开，在此之前文档显示 PDF 预览。边缘代理前面如果还有代理，必须允许至少 200 MiB 的请求体，才能完成上传。安装脚本会复用已缓存的镜像，只在缓存未命中时拉取。

升级会对有变化的服务进行协调，并等待健康检查通过。运行时配置和远程执行节点包只在其输入变化时才同步；单纯的网关版本发布不会重新初始化它们。

私有仓库源访问#

使用私有镜像源时，先用能读取该仓库源的账号让 Docker 完成认证（docker login <registry>），再运行安装脚本。请使用只读的制品凭据或仓库源凭据助手；不要把凭据放进安装目录的 .env、Git 仓库、命令示例或共享的归档中。

网关更新#

稳定的 edge 服务持有对外发布的 HTTP 端口。更新期间，唯一的网关先在就绪探针上返回 503，同时继续处理 edge 已经转发过来的请求。两秒后，它关闭事件流，并在最多 25 秒内处理完普通请求。Compose 会等待 30 秒再强制终止容器。新的进程只在旧进程退出后才启动，因此基于文件的凭据和后台任务不会同时有两个写入者。

Caddy 每 250 毫秒检查一次就绪状态。替换期间到达的请求最多会等待 120 秒，直到有可用的上游。只有 GET 和 HEAD 请求会在上游往返失败后重试。写请求在连接失败时可以等待，此时不会发送请求体；已经发往上游的写请求永远不会被重放。SSE 客户端在旧的事件流关闭后重新连接。这一机制不会持久化并重放客户端断开期间产生的事件。

这是一种有上限的等待策略：正常更新不会出现网关错误，但会增加延迟。客户端必须为切换留出足够的时间。超出排空期限的请求、超时设置更短的客户端、启动失败，以及超过 edge 重试预算的中断，仍然可能导致失败。它不是多副本高可用。对 edge 或有状态依赖的变更同样需要维护窗口；请求等待保证只覆盖仅更新网关的情况。

安装脚本会把网关固定到下载时的摘要（离线归档则固定到本地镜像 ID），保留一份受保护的 .previous-release.* 主机包，并在失败时恢复这份包。scripts/upgrade.sh 会在替换前下载镜像，就绪检查失败时恢复之前的网关镜像和环境。升级失败时仍会以失败状态退出，即使回滚已经成功。数据库迁移必须单独审查：镜像回滚不会撤销数据库变更。如果升级会改动数据库和持久化数据，请事先备份。

CADDY_VERSION 固定官方公开的 caddy:<version>-alpine 边缘代理镜像。正常安装会自动下载它。使用内部仓库源的运维人员可以镜像该版本，并把 CADDY_IMAGE 设为对应的仓库名；这是一项安装配置，不是产品分叉。离线安装必须加载全部六个镜像归档。仅更新网关时，不要改动边缘代理的镜像和配置。