企业微信 AI 机器人助理

Monorepo：backend/ admin/ deploy/ docs/

本地启动

1. 复制环境变量

   cp .env.example .env
   

   Windows PowerShell:

   Copy-Item .env.example .env
   

2. 一键启动

   docker compose up -d
   

3. 访问地址

   • 管理后台（经 nginx）：http://localhost
   • 管理后台（直连）：http://localhost:3000
   • 后端 API（经 nginx）：http://localhost/api/health
   • 后端 API（直连）：http://localhost:8000/api/health
   • PostgreSQL：localhost:5432（仅本机连接）

端口说明

服务	端口	说明
nginx	80	反代，/api→backend，其余→admin
admin	3000	Next.js
backend	8000	FastAPI
db	5432	PostgreSQL

阶段 2：登录与管理员

• 启动后 backend 会自动执行 alembic upgrade head（创建 users、audit_logs 表）。
• 创建管理员：在项目根目录执行 python deploy/scripts/seed.py（依赖见 docs/stage2.md）。
• 后台登录：打开 http://localhost → 登录页，token 存于 localStorage（key: token），详见 admin/lib/api.ts 与 docs/stage2.md。

阶段 1 验证

• GET http://localhost/api/health 或 GET http://localhost:8000/api/health 返回占位 JSON
• GET http://localhost/api/ready 或 GET http://localhost:8000/api/ready 返回占位 JSON
• 浏览器打开 http://localhost 或 http://localhost:3000，可访问 /login、/dashboard 占位页

云端最小回调壳部署

重要：企业微信回调域名必须备案且主体关联，必须先完成云端最小可用部署。

方式一：GitHub Actions 自动部署（推荐）

快速开始（使用配置文件）

1. 使用配置文件自动设置：

   # 配置文件已创建：.github-config（包含你的 GitHub 信息）
   # 自动配置 Git 远程仓库
   .\scripts\setup-github-from-config.ps1
   
   # 推送代码到 GitHub
   .\scripts\push-to-github.ps1
   

手动设置

1. 创建 GitHub 仓库并推送代码：

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/bujie9527/wecom-ai-assistant.git
   git push -u origin main
   

2. 配置 GitHub Secrets：

   • 进入 GitHub 仓库 → Settings → Secrets and variables → Actions
   • 添加以下 Secrets：
     • PROD_HOST: 生产服务器 IP
     • PROD_USER: SSH 用户名
     • PROD_SSH_KEY: SSH 私钥
     • PROD_DOMAIN: 生产域名
     • PROD_APP_PATH: 应用部署路径（可选，默认 /opt/wecom-ai-assistant）

3. 在生产服务器上准备：

   # 安装 Docker
   sudo apt-get update && sudo apt-get install -y docker.io docker-compose-plugin
   
   # 克隆项目
   sudo mkdir -p /opt/wecom-ai-assistant
   cd /opt/wecom-ai-assistant
   git clone https://github.com/YOUR_USERNAME/wecom-ai-assistant.git .
   
   # 配置环境变量
   cp .env.prod.example .env.prod
   nano .env.prod  # 填写生产环境变量
   

4. 触发部署：

   • 推送代码到 main 分支，GitHub Actions 会自动部署
   • 或手动触发：Actions → Deploy to Production → Run workflow

详细文档：参见 docs/github-setup-guide.md

方式二：手动部署

1. 准备环境：

   • 备案域名（例如：api.yourdomain.com）
   • Linux 服务器（Ubuntu 20.04+ / CentOS 7+）
   • Docker + docker-compose

2. 配置环境变量：

   cp .env.prod.example .env.prod
   # 编辑 .env.prod，填写必需变量（WECOM_TOKEN、WECOM_ENCODING_AES_KEY 等）
   

3. 部署最小回调壳：

   # 使用生产配置（backend + nginx）
   docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d
   

4. 配置 HTTPS（Let's Encrypt）：

   export DOMAIN=your-domain.com
   export SSL_EMAIL=your-email@example.com
   bash deploy/scripts/setup-ssl.sh
   

5. 配置企业微信回调：

   • 回调 URL：https://your-domain.com/api/wecom/callback
   • Token：与 .env.prod 中的 WECOM_TOKEN 一致
   • EncodingAESKey：与 .env.prod 中的 WECOM_ENCODING_AES_KEY 一致

详细文档：参见 docs/deploy.md 和 docs/deploy-cloud-minimal.md