Acahti自托管与管理
工作原理
Acahti 实例由哪些部分组成、数据存放在哪里，以及它的插件。
主机#
people ─┐
├─► your TLS proxy or tunnel ─► Acahti control plane ─► Runner
agents ─┘
| 主机 | 运行内容 |
|---|---|
| 控制面 | 网关镜像 ghcr.io/acahti-ai/acahti、Forgejo、Woodpecker server 和 PostgreSQL，以 Docker Compose 运行在 ~/acahti 下。这里不运行流水线 |
| 执行节点 | 一个执行作业的 Woodpecker agent。并行度取决于主机的 CPU 和内存 |
网关#
Go 网关是唯一对外公开的应用。网页端、MCP 和 REST API 都调用同一个内部目录，因此所有入口看到的数据和权限都一致。
| 路径 | 客户端 | 后端 |
|---|---|---|
/ui/* |
浏览器中的用户 | 目录 |
/mcp |
IDE Agent | 目录 |
/acahti/v1 |
CLI、脚本 | 目录 |
/<org>/<repo>.git |
Git | 以已认证用户身份代理到 Forgejo |
/api/packages/* |
npm、pip、uv | 以已认证用户身份代理到 Forgejo |
/hooks/* |
Forgejo、Woodpecker | 索引更新和实时事件 |
列表、「看板」和导航读取网关自己在 PostgreSQL 中的索引。Forgejo webhook 保持仓库数据最新；网关轮询 Woodpecker 的队列，并每分钟对账一次流水线历史。文件内容、diff 和运行中步骤的日志实时从内核读取；失败步骤的日志保存在索引中。
流水线#
推送或 PR 会触发 Woodpecker。作业启动前，网关会展开它的 YAML：官方 pipe 变成 acahti-pipe 调用，具名密钥变成环境变量，每个步骤都会拿到本次运行的 Acahti 身份（ACAHTI_USER、ACAHTI_TOKEN、ACAHTI_ROOT_URL、ACAHTI_ORG）：即头提交作者的账号，找不到时退回到启动这次运行的账号。网关每隔几秒轮询一次 Woodpecker 的队列，每分钟把其历史对账进索引，checks_wait、Inbox 和「看板」都从索引读取。参见流水线。
数据#
所有状态都以 bind mount 的形式存放在 ACAHTI_DATA 下。一旦有了数据，绝不要运行 docker compose down -v。
| 目录 | 内容 |
|---|---|
postgres/ |
Forgejo、Woodpecker 和网关的数据库 |
forgejo/ |
Git 仓库和 Forgejo 状态 |
woodpecker/ |
Woodpecker server 状态 |
gateway/ |
邀请、密码、OAuth 客户端和刷新令牌、个人访问令牌、Argos 运行文件 |
每次升级前都要备份 PostgreSQL 和 ACAHTI_DATA。
独立插件#
Phaevo 是一个单独维护的 GitHub 服务。插件的签名描述文件可以提供一个带自有图标的页头标签、侧栏、页面和 MCP 操作。内核负责验证来源、解析实时身份，并控制访问授权和安装状态。工单、待办、文档、Chat 和 Argos 内置于网关，无需安装插件。
每个插件都支持同样的安装、升级、启用、停用和卸载操作。部署和数据迁移由插件源码仓库的发布流水线负责；卸载会保留应用数据。用户只能看到当前权限允许的页面和操作。
Agent 通过 whoami.plugins 发现自己可访问的插件安装。源码仓库和文档链接在安装元数据中。
供 Agent 读取: how-it-works.md编辑此页