x-server-mobile/REVERSE_PROXY_SETUP.md

反向代理配置指南

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

环境要求

• 已安装 OpenResty 或 Nginx
• 已安装 frpc
• 拥有可用的 frp 服务器
• 拥有可配置的域名

安装步骤

1. 安装 OpenResty (Ubuntu/Debian)

# 导入 GPG 密钥
wget -qO - https://openresty.org/package/pubkey.gpg | sudo apt-key add -

# 添加 OpenResty 仓库
sudo apt-get -y install -y wget gnupg ca-certificates
wget -O - https://openresty.org/package/pubkey.gpg | sudo apt-key add -
echo "deb http://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list

# 安装 OpenResty
sudo apt-get update
sudo apt-get install -y openresty

# 启动服务
sudo systemctl start openresty
sudo systemctl enable openresty

2. 配置 OpenResty

将 nginx/x-server-api.conf 复制到 OpenResty 配置目录：

sudo cp nginx/x-server-api.conf /usr/local/openresty/nginx/conf/conf.d/
sudo mkdir -p /usr/local/openresty/nginx/logs
sudo openresty -s reload

3. 安装 frpc

# 下载 frpc（根据你的系统选择版本）
wget https://github.com/fatedier/frp/releases/download/v0.52.3/frp_0.52.3_linux_amd64.tar.gz

# 解压
tar xzf frp_0.52.3_linux_amd64.tar.gz
cd frp_0.52.3_linux_amd64

# 复制到系统路径
sudo cp frpc /usr/local/bin/
sudo chmod +x /usr/local/bin/frpc

4. 配置 frpc

编辑 frpc/frpc.ini，填入你的 frp 服务器信息：

[common]
server_addr = your-frp-server.com  # 你的 frp 服务器地址
server_port = 7000                  # frp 服务器端口
token = your-frp-token              # 认证令牌

[x-server-api]
type = http
local_ip = 127.0.0.1
local_port = 8787
custom_domains = api.x-server.your-domain.com  # 你的公网域名

5. 启动 frpc

# 前台运行（测试）
frpc -c frpc/frpc.ini

# 后台运行（生产）
nohup frpc -c frpc/frpc.ini > /dev/null 2>&1 &

6. 配置 DNS

将你的域名 api.x-server.your-domain.com 的 A 记录指向你的 frp 服务器 IP。

7. 配置飞书应用

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

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

验证配置

测试本地 API

curl http://localhost:8787/api/v1/user/info

测试反向代理

curl http://api.x-server.local/api/v1/user/info

测试公网访问

curl https://api.x-server.your-domain.com/api/v1/user/info

常见问题

frpc 连接失败

1. 检查 frp 服务器是否在线
2. 检查 token 是否正确
3. 检查端口是否被防火墙阻止

域名无法访问

1. 检查 DNS 解析是否生效
2. 检查 frp 服务器是否配置了该域名
3. 检查 frpc 日志

CORS 错误

如果前端调用 API 时出现 CORS 错误，检查 nginx 配置中的 CORS 头部设置。

安全建议

1. 生产环境务必使用 HTTPS
2. 配置 IP 白名单限制访问
3. 使用强密码和 token
4. 定期更新 frp 和 OpenResty 版本
5. 配置防火墙规则