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

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

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

前提条件

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

配置步骤

1. OpenResty 配置

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

# /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;
    }
}

重载配置：

sudo openresty -s reload
# 或
sudo systemctl reload openresty

2. frpc 配置

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

# ~/.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：

frpc -c ~/.frpc.ini

3. 本地 hosts 配置

在本地开发时配置 hosts：

# /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. 本地测试

# 直接访问后端
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. 公网测试

# 通过 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 配置

常用命令

# 查看 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 文件用于开发环境：

# 后端配置
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 相关配置。