x-server-mobile/docs/ENVIRONMENT.md

环境配置说明

本文档说明开发环境和生产环境的区别，避免混淆。

---

一、环境对比

项目	开发环境	生产环境
Git 分支	feature/mzl-dev	master
服务器	本地 WSL2	45.153.130.80
域名	xsm.dev.hnxinyouhe.com	uniservice-mobile.hnxinyouhe.com
前端端口	5173 (Vite Dev)	静态文件托管
后端端口	8787 (Webman)	8787 (Webman)
代理	OpenResty 8080 + frpc 内网穿透	OpenResty 80/443
数据库	1Panel-mysql-409s	生产 MySQL 容器
调试模式	APP_DEBUG=true	APP_DEBUG=false
日志级别	debug	info

---

二、域名使用说明

开发环境域名

xsm.dev.hnxinyouhe.com

• 用途：飞书登录回调调试
• 通过 frpc 内网穿透暴露到公网
• 只在开发时使用

生产环境域名

uniservice-mobile.hnxinyouhe.com

• 用途：正式生产环境
• 用户实际访问的域名
• 飞书开放平台配置的回调地址

---

三、飞书开放平台配置

生产环境配置（重要！）

飞书开放平台必须配置生产环境的回调地址：

配置项	值
重定向 URL	https://uniservice-mobile.hnxinyouhe.com/login/callback
可信域名	uniservice-mobile.hnxinyouhe.com

注意：开发环境使用 frpc 穿透，但飞书回调仍需要配置正式域名。开发时可以临时添加开发域名到白名单进行测试。

---

四、Git 工作流程

┌─────────────────────────────────────────────────────────────┐
│                      开发环境 (本地)                          │
│                   feature/mzl-dev 分支                       │
└───────────────────────────┬─────────────────────────────────┘
                            │ 开发、测试
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      合并到 master                           │
│                     git merge feature/mzl-dev                │
└───────────────────────────┬─────────────────────────────────┘
                            │ 推送到远程
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    生产服务器拉取                             │
│              ssh root@45.153.130.80                          │
│              git pull origin master                          │
└───────────────────────────┬─────────────────────────────────┘
                            │ 重新构建部署
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   生产环境更新完成                            │
└─────────────────────────────────────────────────────────────┘

日常开发命令

# 1. 开发环境：在 feature/mzl-dev 分支工作
git checkout feature/mzl-dev
git pull origin feature/mzl-dev
# ... 开发、提交 ...
git add .
git commit -m "feat: xxx"
git push origin feature/mzl-dev

# 2. 发布上线：合并到 master
git checkout master
git pull origin master
git merge feature/mzl-dev --no-edit
git push origin master
git checkout feature/mzl-dev  # 切回开发分支

# 3. 生产服务器：拉取并部署
ssh root@45.153.130.80
cd /opt/x-server-mobile
git pull origin master
# 后端已在容器中，只需重启
docker restart x-server-backend
# 前端需重新构建

---

五、前端构建

开发环境

cd /www/x-server-mobile/frontend
npm run dev
# 访问: http://localhost:5173

生产环境

cd /www/x-server-mobile/frontend
npm run build --mode production
# 生成文件: frontend/dist/

# 上传到生产服务器
rsync -avz --delete frontend/dist/ root@45.153.130.80:/www/sites/uniservice-mobile.hnxinyouhe.com/index/

---

六、环境变量配置

开发环境 (.env)

APP_ENV=local
APP_DEBUG=true
DB_HOST=127.0.0.1
DB_PASSWORD=mysql_xEsdPa

生产环境 (.env.production)

APP_ENV=production
APP_DEBUG=false
DB_HOST=1Panel-mysql-prod-xxxx
DB_PASSWORD=strong_production_password

注意：生产环境密码和密钥不要提交到代码仓库！

---

七、常见操作错误

❌ 错误操作

1. 在 master 分支直接开发新功能
2. 在开发环境修改生产数据库
3. 用开发域名 xsm.dev.hnxinyouhe.com 配置飞书开放平台
4. 将生产环境 .env.production 提交到 git
5. 忘记合并到 master 就让生产服务器拉取

✅ 正确操作

1. 始终在 feature/mzl-dev 分支开发
2. 开发完成后合并到 master
3. 生产服务器只拉取 master 分支
4. 敏感配置使用环境变量，不提交到代码
5. 飞书开放平台配置生产环境域名

---

八、调试飞书登录

开发环境调试

# 1. 确保开发服务器运行
cd /www/x-server-mobile/frontend
npm run dev

# 2. 确保后端运行
docker logs x-server-backend -f

# 3. 确保内网穿透运行
frpc -c /www/x-server-mobile/frpc/frpc-dev.ini

# 4. 访问环境检测页
https://xsm.dev.hnxinyouhe.com/feishu-env-test?company=2

# 5. 访问登录页
https://xsm.dev.hnxinyouhe.com/login?company=2

生产环境测试

# 直接访问生产域名
https://uniservice-mobile.hnxinyouhe.com/login?company=2

# 查看生产后端日志
ssh root@45.153.130.80
docker logs x-server-backend -f

---

九、部署检查清单

上线前检查：

• 代码已合并到 master 分支
• 前端已执行 npm run build --mode production
• 生产服务器已拉取最新代码 (git pull origin master)
• 后端容器已重启 (docker restart x-server-backend)
• 前端静态文件已上传到生产服务器
• 飞书开放平台配置的是生产环境域名
• 环境变量配置正确（数据库、Redis、密钥等）

---

十、快速参考

环境判断

// 前端判断开发/生产环境
const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD

// 后端判断（PHP）
$appEnv = config('app.env'); // local, production
$isDebug = config('app.debug'); // true, false

API 地址

// 开发环境：通过代理访问
const API_BASE = '/api/v1'

// 生产环境：同样通过代理访问（OpenResty）
const API_BASE = '/api/v1'

回调地址

// 开发环境（调试用）
const CALLBACK_URL = 'https://xsm.dev.hnxinyouhe.com/login/callback'

// 生产环境（正式）
const CALLBACK_URL = 'https://uniservice-mobile.hnxinyouhe.com/login/callback'

---

最后更新: 2026-02-28