Self-hosted 安装

本指南将带你从零开始，在机器或服务器上运行 Almirant 实例。

预计用时：15-25 分钟（首次运行时大部分时间用于构建 Docker 镜像）。

前提条件

已安装并运行 Docker 24+ 和 Docker Compose v2。若将 Mac 作为终端服务器运行 stack，请先阅读 macOS Docker runtime。
4 GB RAM 和 约 10 GB 可用磁盘空间。
可访问 GitHub 上的 almirant-ai/almirant 仓库。在仓库仍为私有时，你需要可用的 git 身份验证方式（参见第 1 步）。仓库公开后此步骤不再需要。
服务访问使用的公开 URL，可以是：
- 本地使用的 http://localhost:8080。
- 带 HTTPS 的自有域名。
- Tailscale Funnel URL（https://<host>.<tailnet>.ts.net）。
- 隧道 URL（Cloudflare Tunnel、ngrok 等）。

macOS Docker runtime

在 macOS 上，Docker 在 Linux VM 内运行。runtime 是管理该 VM 的应用。有三种选择：

Runtime	最适合	取舍
Docker Desktop	打开 UI 的 Mac 开发环境	较重（空闲时约 500 MB），需要活动 GUI 会话
OrbStack	打开 UI 的 Mac 开发环境	很快，menubar app；需要活动 GUI 会话，商业用途付费
Colima	Headless 服务器	纯 CLI，作为 macOS service 启动；无需 GUI 登录即可跨重启运行，免费

将 Mac 用作服务器时（仅 SSH 访问）

Docker Desktop 和 OrbStack 是需要用户登录图形会话的 macOS apps。若 Mac 重启且无人解锁，Docker daemon 将无法运行，实例也不会启动。

对于服务器用途，请使用 Colima：

brew install colima docker docker-compose

# Sizing tipico para un Mac de 16 GB / 8 cores
colima start --cpu 4 --memory 6 --disk 40

# Que arranque solo al boot (sin necesidad de login GUI)
colima stop
brew services start colima

验证其是否响应：

docker ps   # debe responder en menos de un segundo

使用现有数据切换 runtime

从 OrbStack/Desktop 切换到 Colima 会删除卷（卷位于旧 runtime 的 VM 内）。如果已有重要数据：

在旧 runtime 仍运行时导出：Postgres 使用 pg_dump；如使用 Redis，则手动创建 snapshot。
停止 stack：almirant down。
安装并启动 Colima。
切换 context：docker context use colima。
再次运行 almirant install 或 almirant upgrade 以创建新卷。
恢复 dumps。

如果实例是新的或为空，请直接进入第 1 步。

第 1 步：向 GitHub 验证 git

信息

Almirant 仓库公开后，此步骤将消失。如果在迁移后阅读本文，请跳过它。

安装程序执行 git clone https://github.com/almirant-ai/almirant.git。若仓库私有，git 会请求凭据。最简洁的方式是使用 gh：

# Instala gh si no lo tienes
brew install gh           # macOS
sudo apt install gh       # Debian/Ubuntu

# Login interactivo — elige protocolo HTTPS (no SSH)
gh auth login
# GitHub.com → HTTPS → Login with a web browser

# Configura git para usar las credenciales de gh
gh auth setup-git

验证是否已配置 gh 的 credential helper：

git config --global --get-all credential.https://github.com.helper
# Debe mostrar: !/opt/homebrew/bin/gh auth git-credential   (o similar)

若在 macOS 上 clone 时看到 failed to get: -25308，说明 Keychain 被锁定（常见于没有图形 UI 的 SSH 会话）。请解锁：

security unlock-keychain ~/Library/Keychains/login.keychain-db

第 2 步：安装 CLI

bun add -g almirant@latest
# o
npm i -g almirant

第 3 步：运行 `almirant install`

最推荐的方式是从一开始就传入你将用于访问服务的精确 URL：

almirant install --public-url https://almirant.miempresa.com

公开 URL 的重要性

almirant install 会同时将公开 URL 写入四个变量：

NEXT_PUBLIC_SITE_URL（编译到前端 bundle 中）
BETTER_AUTH_URL
BETTER_AUTH_TRUSTED_ORIGINS
CORS_ORIGIN

如果之后从不同 URL 访问（例如设置了 http://localhost:8080，但通过 https://mimac.tailnet.ts.net 进入），Better-Auth 会以 Invalid origin 拒绝请求，注册将失败。

修改 URL 需要重新构建前端。参见更改公开 URL。

安装程序会：

检查要求（Docker 加 Compose v2）。
将 almirant-ai/almirant 克隆到 ~/.almirant/stack（已存在时 fast-forward）。
如果 .env.production 不存在，则生成含随机密钥的文件。
构建 Docker 镜像（backend、frontend、runner、db-init、shims 等）。首次需要 10-20 分钟。
通过 docker compose up -d 启动 stack。
等待 frontend 变为 healthy。
输出最终 URL 和第 2 天命令。

重要的 `install` flags

Flag	何时使用
`--public-url`	尽可能始终使用，可避免之后重建。
`--non-interactive`	CI 或自动化供应脚本。
`--with-proxy`	希望使用集成反向代理（Caddy），而不是直接暴露端口。
`--with-discord`	将使用 Discord bridge。
`--branch`	固定到特定版本（`v1.2.3`）而非 `main`。
`--from-dir`	使用磁盘中已有 clone 的 air-gapped 安装。

完整列表参见参考 → install。

第 4 步：完成 onboarding

打开安装程序输出的 URL。首次访问会进入 /signup。

数据库为空时（首次干净启动），表单使用 initial_admin_setup 模式：第一个注册用户会创建为 admin，并重定向到 /onboarding 向导。
已有用户时（例如重装并复用同一个 Postgres 卷），表单按正常注册运行：新用户不是 admin，且会进入 dashboard。若要强制重新创建首个 admin，请参见从零开始。

/onboarding 向导包含三个步骤，均带有 "Skip for now" 按钮：

Admin account：确认首位管理员存在，并关闭开放注册。
Public URL (Tailscale)：使用 Tailscale Funnel 发布实例，或粘贴自己的外部 URL。
GitHub App：使用预填 manifest 创建 GitHub App，或接受已有凭据，让智能体可以打开 PR。

完成后应用即可使用。/onboarding 链接会显示在 sidebar 中，直到完成全部步骤。

可选步骤：使用 Tailscale 保护 Postgres

默认情况下，Postgres 位于 Docker 内，不得暴露在 VPS 的公开接口上。若要从笔记本电脑通过 TablePlus、DBeaver、DataGrip 或 psql 连接，安全的方式是使用 Tailscale 创建私有访问。

方案如下：笔记本电脑加入正常的 Tailscale tailnet；Almirant 创建名为 almirant-db 的独立节点；该节点仅在 Tailscale 私有网络监听，并将端口 5432 转发至 Docker 内部 Postgres；Postgres 不会发布到互联网。

不要在 VPS firewall 中开放 Postgres

不要发布 5432:5432，也不要为了测试而向互联网开放端口 5432。这虽可行，但安全基础很差。数据库只能由 tailnet 中的已授权设备访问。

1. 准备 tailnet

先在笔记本电脑安装 Tailscale 并登录。在 Tailscale 面板的 Machines 中确认机器显示。然后在 Access controls 中为数据库节点声明 tag：

"tagOwners": {
  "tag:almirant-db": ["autogroup:admin"]
}

如果已有 tagOwners，不要整体替换，只添加 tag:almirant-db 条目。

2. 限制可访问 Postgres 的主体

添加规则，仅允许你的用户通过 TCP 5432 访问数据库节点：

"grants": [
  {
    "src": ["[email protected]"],
    "dst": ["tag:almirant-db"],
    "ip": ["tcp:5432"]
  }
]

将 [email protected] 替换为登录 Tailscale 使用的电子邮件。

从简单方式开始

如果刚开始使用 Tailscale，请使用 Auth Key。OAuth client 流程更适合高级自动化，但首次配置不需要其额外概念。

3. 为 Almirant 创建 Auth Key

在 Tailscale Admin 中：

进入 Keys。
单击 Generate auth key。
使用 Almirant DB 等描述。
启用 tag:almirant-db tag。
如果 tailnet 需要设备批准，将 key 标记为 pre-approved。
复制 key；它必须以 tskey-auth-... 开头。

不要将此 key 保存在仓库中，也不要粘贴到 issues、日志或截图中。

4. 将 Almirant 连接到 tailnet

以 admin 身份进入 Almirant，然后访问：

/settings/instance

在 Private database access 中：

字段	推荐值
Hostname	`almirant-db`
Tag	`tag:almirant-db`
Method	`Auth key`
Auth key	Tailscale 的 `tskey-auth-...` key

单击 Connect。在 provisioning 状态期间等待其变为 connected。

完成后，Almirant 会显示类似以下的 connection string：

postgresql://...@almirant-db.<tu-tailnet>.ts.net:5432/...

在已连接 Tailscale 的笔记本电脑上使用此 URL。

5. 无法连接时的检查清单

按以下顺序检查：

笔记本电脑已连接 Tailscale。
Tailscale Admin 中有名为 almirant-db 的机器。
该机器具有 tag:almirant-db tag。
访问规则允许到 tag:almirant-db 的 tcp:5432。
Almirant 中 Private database access 状态为 connected。
使用 Almirant 显示的 connection string，而不是容器内部的 DATABASE_URL。

如果 MagicDNS 无法解析 hostname，暂时使用 Almirant 显示的 Tailscale IP 100.x.y.z。

第 5 步：将 CLI 连接到实例

至此已安装stack。现在配置 CLI 指向该实例，以便在仓库中使用 init / link。从每台要使用 CLI 的机器（笔记本电脑、开发 VM、服务器本身等）各执行一次。

5.1：识别 API URL

API URL 是安装时的 --public-url 加上末尾 /api：

`--public-url` of install	API URL
`https://almirant.miempresa.com`	`https://almirant.miempresa.com/api`
`https://<host>.<tailnet>.ts.net`	`https://<host>.<tailnet>.ts.net/api`
`http://localhost:8080`	`http://localhost:8080/api`

5.2：验证 CLI

从要使用 CLI 的机器执行：

# Instala el CLI si aun no lo tienes en esa maquina
bun add -g almirant@latest

# Login contra tu instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

浏览器会打开你的实例；授权会话后，CLI 会获取 API key 并将其保存到 ~/.almirant/config.json。账户有稳定 ID 和可重命名的本地标签。

从另一台机器操作

此步骤与 stack 运行位置无关。若 stack 位于远程服务器而想从笔记本电脑使用 CLI，只需确保笔记本能通过 HTTPS 访问 API URL。若实例位于 Tailscale 后，请确保位于同一 tailnet；若位于 tunnel/proxy 后，请确保端口可访问。

5.3：验证配置

almirant accounts list
almirant current

应看到列出的 self-hosted 账户，API URL 指向实例，API key 仅显示前缀。若有多个账户（例如也使用 almirant.ai 的 SaaS），请设置标签并选择活动账户：

almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro

更多内容参见使用多个账户。

5.4：关联仓库

完成账户验证后，将仓库关联到实例项目与 SaaS 流程完全相同：

cd mi-repo
almirant link
# Si tienes varias cuentas, elige la self-hosted
# Selecciona un proyecto o crea uno nuevo

CLI 会写入包含 almirant mcp proxy --project-id ... --account ... 的 .mcp.json。API key 不在仓库中：它保存在 ~/.almirant/config.json，由代理在内存中附加。

完整分步流程（包括从 IDE 验证）见 连接仓库。

从零开始

若发生问题并希望使用干净数据库重新开始（会销毁本地 stack 的全部数据）：

almirant down --volumes
almirant install --public-url https://almirant.miempresa.com

注意

almirant down --volumes 会删除 Postgres 和 Redis 卷。仅在测试安装或确定想丢弃数据时使用。

首次安装的常见错误

`password authentication failed for user "almirant"`

这表示 Postgres 卷中存在先前安装的旧密码，与刚在 .env.production 中生成的密码不同。Postgres 仅在卷的首次启动时读取 env 中的 POSTGRES_PASSWORD。

修复：删除卷并重新安装（参见从零开始）。

注册时出现 `Invalid origin`

访问 URL 不在 BETTER_AUTH_TRUSTED_ORIGINS 中。

修复：使用与浏览器地址栏完全一致的 URL 重新安装：

almirant install --public-url https://<lo-que-ves-en-tu-navegador>

若已有不希望丢失的数据，可不重装直接更改 URL：参见更改公开 URL。

注册后 404

最常见原因是用户没有 admin 角色（DB 中已有先前尝试创建的用户），重定向将其发送到 /board；若尚未创建项目，该页面可能失败。

修复：从零开始，使首次注册使用 initial_admin_setup 模式。

`docker ps` 挂起或无响应

Docker 客户端在等待 daemon socket。如果 socket 指向未运行的 runtime，就会挂起。

快速诊断：

docker context ls
# Mira que context tiene el `*` y a que socket apunta.

ls -la /var/run/docker.sock 2>&1
ls -la ~/.docker/run/docker.sock 2>&1
ls -la ~/.orbstack/run/docker.sock 2>&1
# El socket del context activo tiene que existir y tener permiso de escritura.

pgrep -lf -i 'OrbStack|Docker Desktop|colima' | head -5
# Tiene que aparecer al menos uno.

按场景修复：

已安装 Docker Desktop 或 OrbStack，但 app 已关闭：打开 app：open -a OrbStack（或 open -a "Docker Desktop"）；等待 30-60 秒后重试 docker ps。
App 已启动但 VM 僵死：关闭后重新打开；若使用 Colima，运行 colima stop && colima start。
切换了 runtime，context 指向旧 runtime：执行 docker context use colima（或正确名称）。
将 Mac 用作服务器且需要跨重启运行：将 Colima 迁移为 service（参见macOS Docker runtime）。

构建期间出现 `lockfile had changes, but lockfile is frozen`

RUN bun install --frozen-lockfile
error: lockfile had changes, but lockfile is frozen

发生原因是 stack 仓库引入新的 bun workspace，但某个 Dockerfile 未更新以将它复制到 builder context。这是 stack bug，而非安装问题。

修复：对 stack 仓库执行 git pull 获取含修复的最新版本，并重试：

cd ~/.almirant/stack
git pull --ff-only origin main
almirant upgrade

若 stack 版本早于修复且不能升级，请在 bun install 之前，手动将 COPY services/<workspace>/package.json ./services/<workspace>/package.json 行添加到受影响的 Dockerfiles。

macOS 上的 Docker keychain 错误

当在没有图形会话的 Mac 上通过 SSH 操作时，会出现 error getting credentials — err: exit status 1, out: keychain cannot be accessed。

快速修复：

security unlock-keychain ~/Library/Keychains/login.keychain-db

永久修复（仅当始终通过 SSH 操作时）：

# Desconecta Docker del keychain
jq 'del(.credsStore, .credHelpers)' ~/.docker/config.json > ~/.docker/config.json.tmp \
  && mv ~/.docker/config.json.tmp ~/.docker/config.json

下一步

Stack 已运行，admin 已创建，onboarding 已完成。若要日常运维实例（日志、升级、备份、URL 变更），请进入 运维 stack。

前提条件​

macOS Docker runtime​

使用现有数据切换 runtime​

第 1 步：向 GitHub 验证 git​

第 2 步：安装 CLI​

第 3 步：运行 almirant install​

重要的 install flags​

第 4 步：完成 onboarding​

可选步骤：使用 Tailscale 保护 Postgres​

1. 准备 tailnet​

2. 限制可访问 Postgres 的主体​

3. 为 Almirant 创建 Auth Key​

4. 将 Almirant 连接到 tailnet​

5. 无法连接时的检查清单​

第 5 步：将 CLI 连接到实例​

5.1：识别 API URL​

5.2：验证 CLI​

5.3：验证配置​

5.4：关联仓库​

从零开始​

首次安装的常见错误​

password authentication failed for user "almirant"​

注册时出现 Invalid origin​

注册后 404​

docker ps 挂起或无响应​

构建期间出现 lockfile had changes, but lockfile is frozen​

macOS 上的 Docker keychain 错误​

下一步​