部署指南

ACE = AI Computing Explorer

本指南涵盖 Open ACE 在各种场景下的部署方法。

快速开始

本地部署

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

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

# 运行数据库迁移
alembic upgrade head

# 启动 Web 服务器
python3 server.py

# 访问 http://localhost:5000

Docker 部署

前提条件

已安装 Docker 和 Docker Compose
Open ACE Docker 镜像（open-ace:latest）
PostgreSQL 镜像（postgres:15-alpine）

初始部署

# 1. 导出 Docker 镜像（在开发机上）
./scripts/export-image.sh --compress

# 2. 复制到服务器
scp dist/open-ace-images.tar.gz user@server:~
scp scripts/deploy.sh user@server:~

# 3. 运行部署脚本
chmod +x deploy.sh
sudo ./deploy.sh

# 4. 按照交互提示操作

部署配置

部署脚本将提示以下配置：

设置	说明	默认值
运行用户	运行应用的用户	`open-ace`
部署目录	安装目录	`/home/open-ace/open-ace`
Web 端口	Web 服务器端口	`5000`
主机名	服务器主机名	自动检测
数据库用户	PostgreSQL 用户名	`open-ace`
数据库名称	PostgreSQL 数据库名	`ace`
OpenClaw	启用 OpenClaw 工具	`yes`
Claude	启用 Claude 工具	`yes`
Qwen	启用 Qwen 工具	`yes`
工作区	启用工作区	`no`

注意：工作区在单独的容器中运行。启用后，Open ACE 将连接到指定 URL 的工作区服务。请确保工作区容器正在运行且端口可访问。

URL 配置：如果在工作区或 OpenClaw URL 中输入 localhost，部署脚本会自动将其转换为服务器 IP 地址。这是因为：

URL 由前端（浏览器）使用，而非容器
浏览器无法将 localhost 解析为服务器地址
示例：http://localhost:3000 → http://192.168.1.100:3000

默认凭证

部署完成后，使用以下凭证登录：

用户名: admin
密码: admin123

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

目录结构

/home/open-ace/open-ace/
├── config/                  # 配置文件
│   └── config.json          # 主配置文件
├── docker-compose.yml       # Docker Compose 配置
└── .env                     # 环境变量（敏感信息！）

注意：数据存储在 PostgreSQL 容器的卷（postgres-data）中，而非主机文件系统。

管理命令

cd /home/open-ace/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 镜像

发布新版本时，只需更新 Docker 镜像：

方法一：简单重启（推荐）

cd /home/open-ace/open-ace

# 1. 加载新镜像
gunzip -c open-ace-images.tar.gz | docker load

# 2. 重启 open-ace 容器
docker compose up -d open-ace

# 3. 验证启动
docker compose logs -f open-ace

方法二：完整重建

cd /home/open-ace/open-ace

# 1. 加载新镜像
gunzip -c open-ace-images.tar.gz | docker load

# 2. 停止并删除旧容器
docker compose stop open-ace
docker compose rm -f open-ace

# 3. 启动新容器
docker compose up -d open-ace

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

方法三：使用版本标签

# 1. 加载特定版本
docker load -i open-ace-v1.2.0.tar

# 2. 更新 docker-compose.yml
sed -i 's|image: open-ace:latest|image: open-ace:v1.2.0|' docker-compose.yml

# 3. 重建容器
docker compose up -d open-ace

注意：

数据存储在 ./data 目录和 PostgreSQL 卷中，不会丢失
./config 中的配置会被保留
PostgreSQL 容器继续运行，只更新 open-ace 容器

数据库迁移

如果新版本包含数据库模式变更：

cd /home/open-ace/open-ace

# 运行迁移
docker compose run --rm open-ace alembic upgrade head

# 重启应用
docker compose restart open-ace

卸载

cd /home/open-ace/open-ace

# 交互式卸载（保留数据）
./uninstall.sh

# 完全卸载（删除所有内容）
./uninstall.sh --purge

配置

配置文件

配置存储在 ~/.open-ace/config.json：

{
  "host_name": "my-machine",
  "tools": {
    "claude": {
      "enabled": true,
      "log_path": "~/.claude/projects"
    },
    "qwen": {
      "enabled": true,
      "log_path": "~/.qwen/projects"
    },
    "openclaw": {
      "enabled": true,
      "log_path": "~/.openclaw/agents"
    }
  },
  "email": {
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "sender": "noreply@example.com"
  }
}

环境变量

变量	说明
`OPENCLAW_TOKEN`	OpenClaw API token
`SMTP_PASSWORD`	邮件 SMTP 密码

部署场景

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

所有组件运行在一台机器上：

# 启动 Web 服务器
python3 server.py

# 设置定时数据采集
crontab -e

添加到 crontab：

# 每天 00:30 采集数据
30 0 * * * cd /path/to/open-ace && python3 scripts/fetch_claude.py && python3 scripts/fetch_qwen.py >> logs/cron.log 2>&1

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

适用于分布式环境：

中心服务器

# 部署
python3 scripts/manage.py local deploy

# 启动 Web 服务
python3 scripts/manage.py local start

远程机器

# 部署到远程
python3 scripts/manage.py remote deploy

# 或手动配置
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

数据采集

手动采集

# 从所有工具采集
python3 scripts/fetch_claude.py
python3 scripts/fetch_qwen.py
python3 scripts/fetch_openclaw.py

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

定时采集

使用 cron：

# 编辑 crontab
crontab -e

# 添加定时任务
30 0 * * * cd /path/to/open-ace && python3 scripts/fetch_claude.py >> logs/cron.log 2>&1
35 0 * * * cd /path/to/open-ace && python3 scripts/fetch_qwen.py >> logs/cron.log 2>&1
40 0 * * * cd /path/to/open-ace && python3 scripts/fetch_openclaw.py >> logs/cron.log 2>&1

管理命令

# 使用 manage.py
python3 scripts/manage.py local start     # 启动本地服务
python3 scripts/manage.py local stop      # 停止本地服务
python3 scripts/manage.py local status    # 检查状态
python3 scripts/manage.py remote deploy   # 部署到远程
python3 scripts/manage.py remote sync     # 同步文件到远程

升级

# 备份数据
cp ~/.open-ace/usage.db ~/.open-ace/usage.db.backup

# 拉取最新代码
git pull

# 如有需要，运行数据库迁移
alembic upgrade head

# 重启服务
python3 scripts/manage.py local stop
python3 scripts/manage.py local start

故障排查

端口被占用

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

# 终止进程
kill -9 <PID>

数据库被锁定

# 检查运行中的进程
ps aux | grep python

# 维护前停止所有服务

权限问题

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

安全注意事项

认证：在生产环境中启用用户认证
HTTPS：使用反向代理（nginx/Apache）配合 SSL
防火墙：限制对 5000 端口的访问
密钥管理：使用环境变量存储敏感数据

多用户工作区部署

启用 workspace.multi_user_mode 时，Open ACE 为每个用户以各自的 system_account 身份启动独立的 qwen-code-webui 进程。这需要额外的部署配置。

前提条件

服务器已安装 qwen-code-webui
已配置 sudo 以支持用户切换
每个 system_account 对应的用户账户已存在

sudo 配置（必需）

创建 sudoers 文件以允许 Open ACE 服务账户以其他用户身份运行 webui：

# 创建 sudoers 文件
sudo visudo -f /etc/sudoers.d/open-ace-webui

添加以下内容：

# 允许 open-ace 服务账户以任意用户身份运行 qwen-code-webui
# 将 'open-ace' 替换为你的实际服务账户名

open-ace ALL=(ALL) NOPASSWD: /usr/local/bin/qwen-code-webui *
open-ace ALL=(ALL) NOPASSWD: /usr/bin/qwen-code-webui *
open-ace ALL=(ALL) NOPASSWD: /opt/qwen-code-webui/bin/qwen-code-webui *

# 允许 open-ace 以其他用户身份执行文件系统操作
# 多用户模式下目录浏览器和项目创建需要此权限
open-ace ALL=(ALL) NOPASSWD: /usr/bin/test, /usr/bin/ls, /usr/bin/cat, /usr/bin/stat, /usr/bin/mkdir

安全注意事项：

使用完整路径以防止路径操作攻击
NOPASSWD 标志是非交互式服务运行所必需的
仅限于特定的可执行文件路径，不要授予通用的 sudo 权限

qwen-code-webui 安装

在以下位置之一安装 qwen-code-webui：

# 方法一：npm 全局安装（推荐）
npm install -g @ivycomputing/qwen-code-webui

# 验证安装
which qwen-code-webui
# 应输出: /usr/local/bin/qwen-code-webui

# 方法二：手动安装
git clone https://github.com/ivycomputing/qwen-code-webui.git
cd qwen-code-webui
npm install && npm run build
ln -s $(pwd)/bin/qwen-code-webui /usr/local/bin/qwen-code-webui

用户账户要求

每个设置了 system_account 的用户必须具备：

Linux 账户已存在：

# 检查用户是否存在
id <system_account>

# 如需要则创建
sudo useradd -m <system_account>

qwen 目录可访问：

# 确保用户有 .qwen 目录
sudo mkdir -p /home/<system_account>/.qwen/projects
sudo chown -R <system_account>:<system_account> /home/<system_account>/.qwen

端口范围配置

选择不与其他服务冲突的端口范围：

{
  "workspace": {
    "port_range_start": 3100,
    "port_range_end": 3200
  }
}

建议：

使用 3000 以上的端口（避免常用服务端口）
为预期并发用户数分配足够的端口（如 100 个端口支持 100 个用户）
验证端口未被占用：sudo netstat -tlnp | grep 3100-3200

systemd 服务配置

当以 systemd 服务运行 Open ACE 时，确保权限正确：

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

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

# 多用户模式必需
# 允许 sudo 执行
AmbientCapabilities=CAP_SETUID CAP_SETGID

[Install]
WantedBy=multi-user.target

多用户模式故障排查

问题	原因	解决方案
"sudo: no tty present"	sudo 需要密码	在 sudoers 中添加 NOPASSWD
"qwen-code-webui not found"	可执行文件未安装	在 PATH 中安装 webui
"Permission denied"	用户缺少权限	检查 sudoers 配置
端口分配失败	所有端口已占用	增加端口范围或减少 max_instances
进程无法启动	用户账户缺失	创建 system_account 用户

检查多用户状态

# 查看运行中的实例
curl http://localhost:5000/api/workspace/instances

# 查看日志
tail -f /home/open-ace/open-ace/logs/open-ace.log | grep WebUIManager

Windows 兼容性

Windows 不支持多用户模式。 在 Windows 系统上，配置会自动降级为单用户模式（不进行用户切换的直接执行）。这是平台限制，因为 Windows 没有等同于 sudo -u 的功能。

目录​

快速开始​

本地部署​

Docker 部署​

前提条件​

初始部署​

部署配置​

默认凭证​

目录结构​

管理命令​

更新 Open ACE 镜像​

方法一：简单重启（推荐）​

方法二：完整重建​

方法三：使用版本标签​

数据库迁移​

卸载​

配置​

配置文件​

环境变量​

部署场景​

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

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

中心服务器​

远程机器​

系统服务​

Linux (systemd)​

macOS (launchd)​

数据采集​

手动采集​

定时采集​

管理命令​

升级​

故障排查​

端口被占用​

数据库被锁定​

权限问题​

安全注意事项​

多用户工作区部署​

前提条件​

sudo 配置（必需）​

qwen-code-webui 安装​

用户账户要求​

端口范围配置​

systemd 服务配置​

多用户模式故障排查​

检查多用户状态​

Windows 兼容性​

目录

快速开始

本地部署

Docker 部署

前提条件

初始部署

部署配置

默认凭证

目录结构

管理命令

更新 Open ACE 镜像

方法一：简单重启（推荐）

方法二：完整重建

方法三：使用版本标签

数据库迁移

卸载

配置

配置文件

环境变量

部署场景

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

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

中心服务器

远程机器

系统服务

Linux (systemd)

macOS (launchd)

数据采集

手动采集

定时采集

管理命令

升级

故障排查

端口被占用

数据库被锁定

权限问题

安全注意事项

多用户工作区部署

前提条件

sudo 配置（必需）

qwen-code-webui 安装

用户账户要求

端口范围配置

systemd 服务配置

多用户模式故障排查

检查多用户状态

Windows 兼容性