慧行引擎部署指南 (Deployment Guide)

版本: V1.0 最后更新: 2026-03-18 适用环境: Ubuntu 24.04 LTS (远程服务器) 前置条件: 具有 root 权限

---

1. 环境准备

1.1 系统要求

• 操作系统: Ubuntu 24.04 LTS (或更高版本)
• 内存: 至少 4GB (推荐 8GB+)
• 磁盘: 至少 20GB 可用空间
• 网络: 开放端口 3000 (API), 5432 (Postgres), 27017 (Mongo)

1.2 安装 Docker

# 1. 更新包索引
apt update

# 2. 安装依赖
apt install -y ca-certificates curl gnupg

# 3. 添加 Docker 官方 GPG 密钥
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# 4. 设置仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker Engine
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. 验证安装
docker --version
docker compose version

1.3 常见问题：Windows vs Linux

问题: 在 Windows 上开发时，Docker 配置常因路径、权限问题失败。 解决: 生产环境必须使用 Linux (Ubuntu)。所有开发、测试、部署统一在远程 Ubuntu 服务器上进行。

---

2. 部署慧行引擎

2.1 获取代码

cd /root/.openclaw/workspace
git clone <repository-url> huixing-engine  # 如果有 Git 仓库
# 或直接使用现有目录
cd huixing-engine

2.2 配置环境变量 (可选)

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量
nano .env

.env 内容示例:

NODE_ENV=production
DB_HOST=postgres
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=huixing_secret_2026  # 生产环境请修改为强密码
DB_DATABASE=huixing_db

2.3 启动 Docker 容器

# 1. 构建并启动
docker compose up -d --build

# 2. 查看日志
docker compose logs -f api

# 3. 检查容器状态
docker compose ps

预期输出:

NAME                IMAGE                     STATUS
huixing-api         huixing-engine-api        Up
huixing-postgres    postgres:15-alpine        Up
huixing-mongo       mongo:7                   Up

2.4 验证部署

# 测试 API 健康
curl http://localhost:3000/api/v1/engineering/tree?tenantId=test

# 预期返回：空数组 [] 或 JSON 数据

---

3. 故障排查 (Troubleshooting)

问题 1: npm error enoent Could not read package.json

原因: backend 目录缺少 package.json。 解决:

cd /root/.openclaw/workspace/huixing-engine/backend
# 确保 package.json 存在
ls -la package.json
# 如果不存在，需创建或从备份恢复

问题 2: connect ECONNREFUSED (数据库连接失败)

原因: PostgreSQL 容器启动慢于 API 容器。 解决:

# 重启 API 容器 (让它等待数据库就绪)
docker compose restart api

# 查看日志确认连接成功
docker compose logs api | grep "Nest application successfully started"

问题 3: 宝塔面板 Docker 管理器报错 KeyError: 'Labels'

原因: 宝塔面板版本 bug，不影响 Docker 本身运行。 解决: 忽略该错误，使用命令行 docker compose 操作。

问题 4: 端口被占用

原因: 3000/5432/27017 端口已被其他程序占用。 解决:

# 查看端口占用
lsof -i :3000
# 修改 docker-compose.yml 中的端口映射
ports:
  - "3001:3000"  # 改为 3001

---

4. 生产环境注意事项

4.1 安全加固

• 修改默认数据库密码 (huixing_secret_2026)
• 配置防火墙 (UFW): 只开放必要端口
• 启用 HTTPS (使用 Nginx 反向代理)
• 定期更新 Docker 镜像

4.2 数据持久化

• 数据已挂载到 Volume (pgdata, mongodata)
• 容器删除不会丢失数据
• 定期备份 /var/lib/docker/volumes

4.3 性能优化

• 增加 PostgreSQL 内存限制
• 配置 MongoDB 索引
• 使用 Redis 缓存热点数据

---

5. 备份与恢复

5.1 备份数据库

# 备份 PostgreSQL
docker compose exec postgres pg_dump -U postgres huixing_db > backup_$(date +%F).sql

# 备份 MongoDB
docker compose exec mongo mongodump --out=/data/backup

5.2 恢复数据库

# 恢复 PostgreSQL
cat backup_2026-03-18.sql | docker compose exec -T postgres psql -U postgres -d huixing_db

---

6. 下一步

• 阅读 CONFIG_GUIDE.md 配置工程模板
• 阅读 ../TASKS.md 了解开发任务

---

文档结束