x-server-mobile/docs/guides/DEV_REVERSE_PROXY_SETUP.md

# 开发环境反向代理配置指南

本指南用于配置开发环境的 OpenResty 和 frpc，以便将本地 API 暴露到公网调试飞书登录。

## 前提条件

- 已安装并运行 OpenResty
- 已安装并运行 frpc
- Docker 中运行的后端服务 (localhost:8787)

## 配置步骤

### 1. OpenResty 配置

在你的 OpenResty 配置目录中创建以下配置文件：

```nginx
# /usr/local/openresty/nginx/conf/conf.d/x-server-api.conf

server {
    listen 8080;  # 本地开发端口，避免与 80 端口冲突
    server_name api.x-server.local;

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8787/api/;
        proxy_http_version 1.1;
        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;

        # CORS 配置（飞书请求需要）
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
        add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,X-Tenant-Key';

        if ($request_method = 'OPTIONS') {
            return 204;
        }

        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 健康检查
    location /health {
        return 200 "OK\n";
        add_header Content-Type text/plain;
    }
}
```

重载配置：
```bash
sudo openresty -s reload
# 或
sudo systemctl reload openresty
```

### 2. frpc 配置

配置 frpc 将本地 OpenResty 服务暴露到公网：

```ini
# ~/.frpc.ini 或 /etc/frp/frpc.ini

[common]
server_addr = your-frp-server.com  # 你的 frp 服务器地址
server_port = 7000
token = your-token

[x-server-api]
type = http
local_ip = 127.0.0.1
local_port = 8080  # OpenResty 监听端口
custom_domains = api-dev.x-server.your-domain.com  # 开发环境域名

# 可选：启用加密和压缩
use_encryption = true
use_compression = true
```

启动 frpc：
```bash
frpc -c ~/.frpc.ini
```

### 3. 本地 hosts 配置

在本地开发时配置 hosts：

```bash
# /etc/hosts
127.0.0.1 api.x-server.local
```

### 4. 飞书应用配置

在飞书开放平台配置开发环境回调 URL：

```
https://api-dev.x-server.your-domain.com/api/v1/auth/feishu-login
```

## 验证配置

### 1. 本地测试
```bash
# 直接访问后端
curl http://localhost:8787/api/v1/user/info

# 通过 OpenResty 访问
curl http://localhost:8080/api/v1/user/info

# 通过本地域名访问
curl http://api.x-server.local/api/v1/user/info
```

### 2. 公网测试
```bash
# 通过 frps 域名访问
curl https://api-dev.x-server.your-domain.com/api/v1/user/info
```

### 3. 飞书调试
1. 在飞书开放平台创建测试应用
2. 配置回调 URL 为开发环境域名
3. 使用飞书 APP ID 和 APP SECRET 进行测试
4. 检查后端日志查看请求详情

## 开发与生产环境区分

### 开发环境（使用 frpc）
- 域名：`api-dev.x-server.your-domain.com`
- 使用 frpc 暴露本地服务
- CORS 允许所有来源
- 详细日志输出

### 生产环境（不使用 frpc）
- 域名：`api.x-server.com`
- 直接部署到服务器
- CORS 严格限制
- 日志级别调整

## 故障排查

### OpenResty 无法访问后端
1. 检查 Docker 容器是否运行：`docker ps`
2. 检查端口是否正确：`docker ps | grep 8787`
3. 检查网络连通性：`curl http://127.0.0.1:8787`

### frpc 连接失败
1. 检查 frp 服务器是否可访问
2. 检查 token 是否正确
3. 查看 frpc 日志：`frpc -c ~/.frpc.ini`

### 飞书回调失败
1. 检查域名 DNS 解析是否指向 frp 服务器
2. 检查 frp 服务器是否配置了域名白名单
3. 检查后端日志是否收到请求
4. 验证 CORS 配置是否正确

## 安全建议

1. **开发环境使用独立的域名和 token**
2. **定期更新 frp token**
3. **不要在代码中硬编码生产环境配置**
4. **使用环境变量管理敏感信息**
5. **生产环境部署前移除 frpc 配置**

## 常用命令

```bash
# 查看 Docker 容器日志
docker logs x-server-backend -f

# 重启后端服务
docker compose restart backend

# 重载 OpenResty 配置
sudo openresty -s reload

# 查看 frpc 状态
frpc status -c ~/.frpc.ini

# 测试 API 连通性
curl -v http://localhost:8787/api/v1/user/info
```

## 环境变量配置

创建 `.env.development` 文件用于开发环境：

```env
# 后端配置
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=x_server_mobile
DB_USERNAME=root
DB_PASSWORD=mysql_xEsdPa

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379

# 飞书配置（开发环境）
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxx

# API 配置
API_BASE_URL=http://localhost:8787
PUBLIC_API_URL=https://api-dev.x-server.your-domain.com
```

生产环境使用 `.env.production` 文件，移除 frpc 相关配置。