部署

ACE = AI Computing Explorer

本指南涵盖 Open ACE 的部署：Docker 生产路径、无 Docker 的本地试用、配置、数据持久化、数据采集与故障排查。

安全模式必读

任何生产部署之前，必须显式设置安全模式（Issue #2331）：

OPENACE_SECURITY_MODE=production

production——强制安全检查。必须显式设置 SECRET_KEY 和 OPENACE_ENCRYPTION_KEY（各不少于 32 字符）以及强 DB_PASSWORD；弱值或占位符会拒绝启动。
pilot——试用环境。缺失的密钥自动生成，但输出强警告。
development——本地开发。缺失的密钥自动生成，输出一般警告。

最快且正确的做法是使用 bootstrap 脚本，它会写入并校验 .env（OPENACE_SECURITY_MODE=production、强随机的 SECRET_KEY / OPENACE_ENCRYPTION_KEY / DB_PASSWORD）：

./scripts/bootstrap-compose-env.sh

注意事项：

单用户 docker-compose.yml 默认 development，便于一键本地启动；生产环境必须显式设置该变量。
多用户 overlay 在缺少必需密钥时会以 Run ./scripts/bootstrap-compose-env.sh first 快速失败。
生产环境还需设置 SSO_ALLOWED_REDIRECT_DOMAINS（逗号分隔的域名白名单）；未配置时，非 localhost 来源的 SSO 登录会被拒绝（Issue #3224）。
权威环境变量总表见 ENV_REFERENCE.md，密钥轮转影响见 KEY_MANAGEMENT.md。

快速开始（Docker）

Docker Compose 栈会运行 Open ACE 容器和一个 PostgreSQL 15 数据库，所有持久化数据都存放在命名卷中。

# 1. 在服务器上克隆仓库
git clone https://github.com/open-ace/open-ace.git
cd open-ace

# 2. 生成并校验 .env（SECRET_KEY、OPENACE_ENCRYPTION_KEY、DB_PASSWORD 等）
./scripts/bootstrap-compose-env.sh

# 3. 启动（默认拉取 ghcr.io/open-ace/open-ace:latest 预构建镜像）
docker compose up -d --wait

# 4. 验证
docker compose ps
docker compose logs -f open-ace

然后访问 http://localhost:19888，使用默认凭证登录：

用户名: admin
密码: admin123

重要：首次登录后请立即修改默认密码。

说明：

镜像为 ghcr.io/open-ace/open-ace:latest（可用 IMAGE_NAME 覆盖，例如固定为 ghcr.io/open-ace/open-ace:v2.1.0 或本地构建的 open-ace:dev）。开发者可本地构建：docker build -t open-ace:dev --target production .。
docker compose down 不会删除数据；所有状态都在命名卷中（见数据持久化）。
容器默认以非 root 用户 open-ace（uid 1000）运行。只有多用户模式需要 root（见多用户工作区）。
单用户模式下 scheduler 调度worker是可选 profile：docker compose --profile scheduler up -d。
HTTPS 请按 NGINX.md 配置反向代理；Kubernetes 部署见 KUBERNETES.md。

离线安装

无外网服务器可使用 scripts/install-central/docker-method/ 下的镜像导出脚本：

# 在有网络的机器上：构建并导出全部镜像
./scripts/install-central/docker-method/export-image.sh --build --compress

# 将 open-ace-images.tar.gz（及 install.sh）拷贝到目标服务器后执行
./install.sh

也可以用原生 Docker 命令完成：

docker pull ghcr.io/open-ace/open-ace:latest
docker save ghcr.io/open-ace/open-ace:latest | gzip > open-ace-images.tar.gz
gunzip -c open-ace-images.tar.gz | docker load

每个版本的预构建镜像都发布到 GitHub Container Registry（ghcr.io/open-ace/open-ace:latest、:vX.Y.Z、:X.Y.Z、:X.Y、:X），仅提供 linux/amd64，Apple Silicon 主机以模拟方式运行。若无法访问 ghcr.io，可改为从当前代码本地构建：docker compose up -d --build --wait。

国内网络无法访问 Docker Hub 时，在 .env 中设置 BASE_REGISTRY=docker.m.daocloud.io，让构建和 PostgreSQL 镜像都走镜像源。

本地试用（无 Docker）

# 安装依赖
pip install -r requirements.txt

# 初始化配置
python3 cli.py config init

# 运行数据库迁移（首次启动前必需）
alembic upgrade head

# 启动 Web 服务器
python3 server.py

# 访问 http://localhost:19888

开发/试用模式支持零配置启动（Issue #2667）：缺失的 OPENACE_ENCRYPTION_KEY 会在首次启动自动生成并持久化到 ~/.open-ace/generated-secrets.env（重启复用、不轮转）。生产模式仍要求显式设置。

配置

配置分两层：

环境变量（Docker Compose 用 .env）控制部署层事项：端口、数据库、安全模式、多用户开关。含默认值与轮转影响的权威总表见 ENV_REFERENCE.md。
config.json 控制应用行为（采集哪些工具、邮件、工作区）。裸机部署位于 ~/.open-ace/config.json；Docker 部署在首次启动时于 config-data 卷内自动生成（/home/open-ace/.open-ace/config.json），也可以把自定义文件以只读方式挂载到该路径。完整参考见 CONFIG_REFERENCE.md。

多数部署会碰到的环境变量：

变量	默认值	用途
`PORT`	`19888`	宿主机 Web 端口（容器内固定监听 19888）
`SERVER_IP`	自动探测	浏览器访问服务使用的地址（Issue #1306）；从其他机器访问时显式设置，如 `SERVER_IP=192.168.1.100`
`WORKSPACE_PORT_RANGE_START` / `WORKSPACE_PORT_RANGE_END`	`3100` / `3200`	发布的每用户工作区 WebUI 实例端口段
`WORKSPACE_ISOLATION_BACKEND`	`shared`	隔离 backend（Issue #3446）：`plain` = 每用户一个 OS 账户（需多用户 overlay），`opensandbox` = OpenSandbox pod；取代 `WORKSPACE_MULTI_USER_MODE`
`DB_USER` / `DB_NAME`	`ace` / `ace`	PostgreSQL 用户与数据库名
`DB_PASSWORD`	开发默认值	生产环境必须设置强密码
`IMAGE_NAME`	`ghcr.io/open-ace/open-ace:latest`	应用镜像
`BASE_REGISTRY`	`docker.io`	基础镜像仓库覆盖

端口配置

裸机：修改 ~/.open-ace/config.json 的 server.web_port / server.web_host，重启服务。
Docker：临时修改 PORT=5001 docker compose up -d；永久修改 echo "PORT=5001" >> .env 后 docker compose down && docker compose up -d。

防火墙（外网访问）：

# Ubuntu/Debian
sudo ufw allow 19888/tcp

# CentOS/RHEL
sudo firewall-cmd --add-port=19888/tcp --permanent
sudo firewall-cmd --reload

数据持久化

不存在 ./data 目录。所有持久化数据都在 docker-compose.yml 声明的 4 个命名卷中：

卷	挂载点	内容
`config-data`	`/home/open-ace/.open-ace`	`config.json` 与 `generated-secrets.env`
`postgres-data`	`/var/lib/postgresql/data`	PostgreSQL 数据库（用户、会话、全部应用数据）
`workspace-data`	`/workspace`	各用户的项目目录
`agent-state`	`/var/lib/openace`	CLI 会话记录，由应用与 scheduler 服务共享（Issue #3237）

此外，宿主机 ./logs 以绑定挂载方式映射到 /app/logs。多用户部署额外增加第 5 个卷 home-data（挂载 /home），存放用户家目录（Issue #2729）。

查看卷：

docker volume ls | grep open-ace
# 应看到：agent-state、config-data、postgres-data、workspace-data

数据库备份使用 pg_dump（见 DATABASE_BACKUP.md）；postgres-data 卷是唯一可信数据源。

管理命令

cd /path/to/open-ace

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f

# 仅查看 open-ace 日志
docker compose logs -f open-ace

# 重启服务
docker compose restart

# 仅重启 open-ace
docker compose restart open-ace

# 停止服务（卷会保留）
docker compose down

# 启动服务
docker compose up -d

数据采集

Open ACE 通过 scripts/ 下的采集脚本汇聚本地 AI CLI 工具的用量：

脚本	数据来源
`fetch_claude.py`	`~/.claude/projects`（Claude Code JSONL）
`fetch_qwen.py`	`~/.qwen/projects`（Qwen Code JSONL）
`fetch_codex.py`	`~/.codex/sessions`（Codex CLI JSONL）
`fetch_zcode.py`	`~/.zcode/cli/db/db.sqlite`（ZCode CLI SQLite）
`fetch_openclaw.py`	`~/.openclaw/agents`（OpenClaw）

手动采集：

python3 scripts/fetch_claude.py
python3 scripts/fetch_qwen.py
python3 scripts/fetch_codex.py
python3 scripts/fetch_zcode.py
python3 scripts/fetch_openclaw.py

# 采集指定天数
python3 scripts/fetch_claude.py --days 7

定时采集（裸机部署）：

crontab -e

0 * * * cd /path/to/open-ace && python3 scripts/fetch_claude.py >> logs/cron.log 2>&1
0 * * * cd /path/to/open-ace && python3 scripts/fetch_qwen.py >> logs/cron.log 2>&1
0 * * * cd /path/to/open-ace && python3 scripts/fetch_codex.py >> logs/cron.log 2>&1
0 * * * cd /path/to/open-ace && python3 scripts/fetch_zcode.py >> logs/cron.log 2>&1
0 * * * cd /path/to/open-ace && python3 scripts/fetch_openclaw.py >> logs/cron.log 2>&1

部署场景

场景一：单机部署（推荐个人使用）

所有组件在同一台机器：python3 server.py 加上文的 cron 任务。

场景二：中心服务器 + 远程采集器

分布式环境使用 scripts/manage.py 部署。其用法为「位置参数 action + 可选 --remote 开关」：

python3 scripts/manage.py init      # 初始化配置
python3 scripts/manage.py deploy    # 部署到 ~/open-ace/
python3 scripts/manage.py install   # 安装为系统服务
python3 scripts/manage.py start     # 启动 Web 服务器（部署目录）
python3 scripts/manage.py stop      # 停止 Web 服务器
python3 scripts/manage.py restart   # 重启 Web 服务器
python3 scripts/manage.py status    # 检查服务状态
python3 scripts/manage.py show      # 查看当前配置
python3 scripts/manage.py --remote deploy  # 部署到远程机器
python3 scripts/manage.py --remote sync    # 同步文件到远程
python3 scripts/manage.py --remote status  # 检查远程状态

--remote 只支持 deploy、sync、status；sync 仅远程可用。

也可以手动配置远程机器：

scp -r open-ace user@remote:/path/to/
ssh user@remote "cd /path/to/open-ace && python3 scripts/fetch_openclaw.py"

系统服务

Linux (systemd)

创建 /etc/systemd/system/open-ace.service：

[Unit]
Description=Open ACE Web Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/open-ace
ExecStart=/usr/bin/python3 server.py
Restart=always

[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable open-ace
sudo systemctl start open-ace

macOS (launchd)

创建 ~/Library/LaunchAgents/com.open-ace.web.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.open-ace.web</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>/path/to/open-ace/server.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardInPath</key>
    <string>/dev/null</string>
    <key>StandardOutPath</key>
    <string>/path/to/open-ace/server.log</string>
    <key>StandardErrorPath</key>
    <string>/path/to/open-ace/server-error.log</string>
</dict>
</plist>

加载服务：

launchctl load ~/Library/LaunchAgents/com.open-ace.web.plist

多用户工作区

使用 OS 账户类隔离 backend（workspace.isolation.backend 为 plain、bwrap、local-gvisor 或 local-kata）时，Open ACE 为每个用户以各自的 system_account 身份启动独立的 qwen-code-webui 进程。其中 plain 需要容器以 root 运行。启动方式、sudoers 配置与版本要求见 MULTI_USER_WORKSPACE.md。

如何在几种隔离方式（每用户 OS 账户、受约束、本机 gVisor/Kata 容器、OpenSandbox pod）之间选择、如何配置并验证实际生效的隔离，见管理员指南 WORKSPACE_ISOLATION.md。包安装脚本会为你配置 sudoers 规则与 wrapper；MULTI_USER_WORKSPACE.md 中的手工配置适用于不使用安装脚本的安装。

隔离与 Docker 安装。 Docker 安装支持 none 与每用户 os_user 等级，以及通过 Kubernetes 上的 OpenSandbox pod 实现的 sandboxed。受约束的 os_user 与本机 gVisor/Kata 沙箱需要 Linux 主机上的包安装。选择安装方式前请先看 WORKSPACE_ISOLATION。

升级

升级到 v2.1：工作区隔离改为单一的 workspace.isolation {"level", "backend"} 配置块（Issue #3446），旧配置键（multi_user_mode、required_isolation_level、os_user_confinement 等）会使服务器拒绝启动。包安装与 Docker 安装会自动转换配置；源码安装和只读挂载的配置须先运行 python3 scripts/convert_workspace_isolation.py <config.json 路径>。Docker 请用 WORKSPACE_ISOLATION_BACKEND 代替 WORKSPACE_MULTI_USER_MODE。详见工作区隔离。执行 alembic upgrade head（v2.1 新增两个索引，在 PostgreSQL 上构建时不阻塞写入）。

从 v1.x 升级到 v2.0：以 v2.0 重启前请先确认：

源码 / 离线包安装需要 Python 3.10+。

首次重启前把 OPENACE_ENCRYPTION_KEY 设为原 SECRET_KEY 的值（见 KEY_MANAGEMENT.md）。

Docker 镜像以 uid 1000 运行；挂载卷须对其可写，多用户工作区模式请使用 docker-compose.multi-user.yml。

数据库须已处于 baseline_2026_06_23 或之后；执行 alembic upgrade head。

完整列表见 CHANGELOG.md 的 v2.0.0 段落。

拉取新镜像并重启即可；数据库迁移在容器启动时自动执行，且受最低升级基线 baseline_2026_06_23 约束。详细步骤、迁移失败处置与回滚见 UPGRADING.md。

卸载

# 停止并删除容器
docker compose down

# 删除镜像
docker rmi ghcr.io/open-ace/open-ace:latest postgres:15-alpine

# 删除数据卷（彻底清理）
docker volume rm open-ace_agent-state open-ace_config-data open-ace_postgres-data open-ace_workspace-data

# 删除本地配置（可选）
rm -rf ~/.open-ace ./logs

多用户部署还包含 home-data 卷（open-ace_home-data）。卷名带有 Compose 项目前缀（默认克隆目录为 open-ace_）；用 docker volume ls | grep open-ace 列出你的卷。

故障排查

端口被占用

# 查找占用 19888 端口的进程
lsof -i :19888

# 终止进程
kill -9 <PID>

或修改 Open ACE 端口（见端口配置）。

macOS AirPlay 历史注记

历史上，macOS Monterey (12) 及以后版本默认启用 AirPlay Receiver，监听 5000 端口，会与占用该端口的服务冲突。Open ACE 现监听 19888 端口，此冲突已不存在；保留此注记仅作历史参考。若确实遇到端口冲突，可关闭 AirPlay Receiver（系统设置 → 通用 → AirDrop 与接力 → 关闭「AirPlay 接收器」）或修改 Open ACE 端口。

数据库连接失败

docker compose ps
docker compose logs postgres
docker compose logs -f open-ace

确认 PostgreSQL 健康（pg_isready 健康检查通过）且 .env 中的 DB_PASSWORD 匹配。

权限问题

# 修复权限
chmod -R 755 ~/.open-ace/

code-server 安装验证

code-server 用于本地工作区会话的「打开 VS Code」功能：

# 在 Docker 容器中验证
docker run --rm <image> which code-server
docker run --rm <image> code-server --version

错误信息	原因	解决方案
`code-server is not installed`	镜像版本过旧或未正确构建	重新构建 Docker 镜像
`code-server: command not found`	PATH 问题	检查 `/usr/bin/code-server` 是否存在
安装失败	网络问题	检查网络连接，考虑使用代理

目录​

安全模式必读​

快速开始（Docker）​

离线安装​

本地试用（无 Docker）​

配置​

端口配置​

数据持久化​

管理命令​

数据采集​

部署场景​

场景一：单机部署（推荐个人使用）​

场景二：中心服务器 + 远程采集器​

系统服务​

Linux (systemd)​

macOS (launchd)​

多用户工作区​

升级​

卸载​

故障排查​

端口被占用​

macOS AirPlay 历史注记​

数据库连接失败​

权限问题​

code-server 安装验证​

相关文档​

目录