# 微信登录服务部署指南

> **文档版本**：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` 文件：

```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 作为反向代理：

```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. 防火墙配置

开放必要端口：

```bash
# HTTPS
sudo ufw allow 443/tcp

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

---

## 部署步骤

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

#### 步骤 1：安装依赖

```bash
cd server
pip install -r requirements.txt
```

#### 步骤 2：运行数据库迁移

```bash
python app/migrations/012_wechat_login_fields.py
```

#### 步骤 3：重启服务

```bash
docker-compose restart api
```

#### 步骤 4：查看日志

```bash
docker-compose logs -f api
```

---

### 方式 2：手动部署

#### 步骤 1：激活虚拟环境

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

#### 步骤 2：安装依赖

```bash
pip install -r requirements.txt
```

#### 步骤 3：运行迁移

```bash
python app/migrations/012_wechat_login_fields.py
```

#### 步骤 4：启动服务

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

---

## 测试验证

### 1. 运行测试脚本

```bash
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：获取二维码

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

**预期响应**：

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

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

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

**预期响应**：

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

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

```bash
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：获取二维码

```typescript
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：展示二维码

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

#### 步骤 3：轮询结果

```typescript
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. 查看服务日志

```bash
# Docker
docker-compose logs -f api

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

### 2. 监控 Redis

```bash
# 查看所有 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. 监控数据库

```sql
-- 查看微信登录用户数
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 分钟）
- ✅ 定期清理过期会话
- ✅ 软删除用户数据

---

## 相关文档

- [微信登录服务设计](../../requirements/backend/04-services/user/wechat-service.md)
- [微信登录服务实现](../changelogs/2026-01-27-wechat-service-implementation.md)
- [用户服务测试指南](./user-service-testing.md)

---

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