docs/v1.0/server/guides/wechat-service-deployment.md

微信登录服务部署指南

文档版本：v1.0
最后更新：2026-01-27

---

目录

1. 前置条件
2. 微信平台配置
3. 服务器配置
4. 部署步骤
5. 测试验证
6. 常见问题

---

前置条件

1. 系统要求

• Python 3.12+
• PostgreSQL 17+
• Redis 5.0+
• Docker & Docker Compose（可选）

2. 依赖服务

• ✅ 数据库服务正常运行
• ✅ Redis 服务正常运行
• ✅ 用户服务已部署

3. 微信账号

• 微信公众号（已认证）
• 微信开放平台账号（可选）

---

微信平台配置

1. 微信公众号配置

步骤 1：登录微信公众平台

访问：https://mp.weixin.qq.com/

步骤 2：获取 AppID 和 AppSecret

1. 进入「开发」→「基本配置」
2. 复制「开发者ID (AppID)」
3. 生成并复制「开发者密码 (AppSecret)」

步骤 3：配置网页授权域名

1. 进入「设置与开发」→「接口权限」→「网页授权」
2. 点击「修改」
3. 填写授权回调域名：api.jointo.ai（不含协议和路径）
4. 下载验证文件并上传到服务器根目录

注意事项

• ⚠️ 域名必须备案
• ⚠️ 必须使用 HTTPS
• ⚠️ 域名不能包含端口号

---

2. 微信开放平台配置

步骤 1：登录微信开放平台

访问：https://open.weixin.qq.com/

步骤 2：创建网站应用

1. 进入「管理中心」→「网站应用」
2. 点击「创建应用」
3. 填写应用信息：
   • 应用名称：Jointo
   • 应用简介：视频制作工作台
   • 应用官网：https://jointo.ai
   • 授权回调域：https://api.jointo.ai/api/v1/auth/wechat/callback

步骤 3：获取 AppID 和 AppSecret

1. 应用审核通过后
2. 进入应用详情
3. 复制「AppID」和「AppSecret」

注意事项

• ⚠️ 需要企业认证
• ⚠️ 审核周期约 7 个工作日
• ⚠️ 回调 URL 必须完整（含协议和路径）

---

服务器配置

1. 环境变量配置

编辑 server/.env 文件：

# 微信公众号配置
WECHAT_MP_APPID=wx1234567890abcdef
WECHAT_MP_SECRET=your_mp_secret_here
WECHAT_MP_CALLBACK_URL=https://api.jointo.ai/api/v1/auth/wechat/callback

# 微信开放平台配置
WECHAT_OPEN_APPID=wx0987654321fedcba
WECHAT_OPEN_SECRET=your_open_secret_here
WECHAT_OPEN_CALLBACK_URL=https://api.jointo.ai/api/v1/auth/wechat/callback

# Redis 配置
REDIS_URL=redis://localhost:6379/0

2. Nginx 配置

如果使用 Nginx 作为反向代理：

server {
    listen 443 ssl http2;
    server_name api.jointo.ai;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /api/v1/auth/wechat/ {
        proxy_pass http://localhost:6170;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. 防火墙配置

开放必要端口：

# HTTPS
sudo ufw allow 443/tcp

# Redis（如果外部访问）
sudo ufw allow 6379/tcp

---

部署步骤

方式 1：Docker Compose 部署（推荐）

步骤 1：安装依赖

cd server
pip install -r requirements.txt

步骤 2：运行数据库迁移

python app/migrations/012_wechat_login_fields.py

步骤 3：重启服务

docker-compose restart api

步骤 4：查看日志

docker-compose logs -f api

---

方式 2：手动部署

步骤 1：激活虚拟环境

cd server
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

步骤 2：安装依赖

pip install -r requirements.txt

步骤 3：运行迁移

python app/migrations/012_wechat_login_fields.py

步骤 4：启动服务

uvicorn app.main:app --host 0.0.0.0 --port 6170 --reload

---

测试验证

1. 运行测试脚本

cd server
python test_wechat_service.py

预期输出：

============================================================
平台枚举转换测试
============================================================

[测试] 字符串 → 枚举值
✅ 'mp' → 1 (MP)
✅ 'open' → 2 (OPEN)

[测试] 枚举值 → 字符串
✅ 1 → 'mp'
✅ 2 → 'open'

============================================================
微信登录服务测试
============================================================

[测试 1] 生成微信登录二维码
------------------------------------------------------------
✅ 场景ID: 01936c8a-7b2e-7890-abcd-ef1234567890
✅ 二维码URL: https://open.weixin.qq.com/connect/oauth2/authorize?...
✅ 过期时间: 300秒
✅ Redis 存储平台: 1 (1=mp, 2=open)

...

============================================================
✅ 所有测试通过
============================================================

2. API 测试

测试 1：获取二维码

curl -X GET "https://api.jointo.ai/api/v1/auth/wechat/qrcode?platform=mp"

预期响应：

{
  "code": 200,
  "message": "Success",
  "data": {
    "sceneId": "01936c8a-7b2e-7890-abcd-ef1234567890",
    "qrcodeUrl": "https://open.weixin.qq.com/connect/oauth2/authorize?...",
    "expiresIn": 300
  }
}

测试 2：轮询结果（未完成）

curl -X GET "https://api.jointo.ai/api/v1/auth/wechat/result?sceneId=xxx"

预期响应：

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "pending"
  }
}

测试 3：绑定微信（需要 Token）

curl -X POST "https://api.jointo.ai/api/v1/auth/wechat/bind" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "061a2b3c4d5e6f7g8h9i0j",
    "platform": "mp"
  }'

3. 前端集成测试

步骤 1：获取二维码

const response = await fetch('https://api.jointo.ai/api/v1/auth/wechat/qrcode?platform=mp');
const { data } = await response.json();
const { sceneId, qrcodeUrl } = data;

步骤 2：展示二维码

// 使用 qrcode.react 或其他库
<QRCode value={qrcodeUrl} size={256} />

步骤 3：轮询结果

const pollInterval = setInterval(async () => {
  const response = await fetch(`https://api.jointo.ai/api/v1/auth/wechat/result?sceneId=${sceneId}`);
  const { data } = await response.json();
  
  if (data.status === 'success') {
    clearInterval(pollInterval);
    // 保存 Token
    localStorage.setItem('accessToken', data.accessToken);
    // 跳转到主页
    router.push('/');
  }
}, 2000); // 每 2 秒轮询一次

---

常见问题

1. 二维码生成失败

错误信息：无效的平台类型

解决方案：

• 检查 platform 参数是否为 mp 或 open
• 检查环境变量是否正确配置

---

2. 微信回调失败

错误信息：redirect_uri 参数错误

解决方案：

• 检查微信平台配置的回调域名
• 确保域名已备案且使用 HTTPS
• 检查 Nginx 配置是否正确

---

3. 轮询一直返回 pending

可能原因：

• 用户未扫码
• 用户未授权
• 微信回调失败

解决方案：

• 检查 Redis 中是否有数据：redis-cli GET wechat:user:{sceneId}
• 检查服务器日志：docker-compose logs -f api
• 检查微信回调 URL 是否可访问

---

4. Token 验证失败

错误信息：无效的访问令牌

解决方案：

• 检查 Token 是否过期
• 检查 SECRET_KEY 配置是否一致
• 检查 Token 格式：Bearer {token}

---

5. Redis 连接失败

错误信息：Connection refused

解决方案：

• 检查 Redis 服务是否运行：redis-cli ping
• 检查 REDIS_URL 配置
• 检查防火墙规则

---

监控与日志

1. 查看服务日志

# Docker
docker-compose logs -f api

# 手动部署
tail -f logs/app.log

2. 监控 Redis

# 查看所有 key
redis-cli KEYS "wechat:*"

# 查看特定 key
redis-cli GET "wechat:scene:{sceneId}"
redis-cli GET "wechat:user:{sceneId}"

# 查看 TTL
redis-cli TTL "wechat:scene:{sceneId}"

3. 监控数据库

-- 查看微信登录用户数
SELECT COUNT(*) FROM users WHERE wechat_openid IS NOT NULL;

-- 查看各平台用户分布
SELECT 
    wechat_platform,
    COUNT(*) as user_count
FROM users 
WHERE wechat_openid IS NOT NULL
GROUP BY wechat_platform;

---

安全建议

1. 环境变量保护

• ✅ 不要将 .env 文件提交到 Git
• ✅ 使用环境变量管理工具（如 Vault）
• ✅ 定期轮换 AppSecret

2. HTTPS 强制

• ✅ 所有 API 必须使用 HTTPS
• ✅ 配置 HSTS 头
• ✅ 使用有效的 SSL 证书

3. 速率限制

• ✅ 限制二维码生成频率（每用户每分钟 5 次）
• ✅ 限制轮询频率（每 2 秒一次）
• ✅ 使用 Redis 实现速率限制

4. 数据清理

• ✅ Redis 数据自动过期（5 分钟）
• ✅ 定期清理过期会话
• ✅ 软删除用户数据

---

相关文档

• 微信登录服务设计
• 微信登录服务实现
• 用户服务测试指南

---

文档版本：v1.0
维护人：Backend Team
最后更新：2026-01-27