From 4617eae0b1f120a07b4ace54ac8d3debb342e06a Mon Sep 17 00:00:00 2001 From: root Date: Sat, 28 Feb 2026 11:24:32 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=8E=AF=E5=A2=83?= =?UTF-8?q?=E9=85=8D=E7=BD=AE=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 包含： - 开发环境与生产环境对比 - 域名使用说明 - Git 工作流程 - 飞书开放平台配置 - 常见操作错误（避免混淆） - 部署检查清单 --- docs/ENVIRONMENT.md | 257 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 docs/ENVIRONMENT.md diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md new file mode 100644 index 0000000..662cf98 --- /dev/null +++ b/docs/ENVIRONMENT.md @@ -0,0 +1,257 @@ +# 环境配置说明 + +本文档说明开发环境和生产环境的区别，避免混淆。 + +--- + +## 一、环境对比 + +| 项目 | 开发环境 | 生产环境 | +|------|----------|----------| +| **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 │ +└───────────────────────────┬─────────────────────────────────┘ + │ 重新构建部署 + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 生产环境更新完成 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 日常开发命令 + +```bash +# 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 +# 前端需重新构建 +``` + +--- + +## 五、前端构建 + +### 开发环境 +```bash +cd /www/x-server-mobile/frontend +npm run dev +# 访问: http://localhost:5173 +``` + +### 生产环境 +```bash +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) +```env +APP_ENV=local +APP_DEBUG=true +DB_HOST=127.0.0.1 +DB_PASSWORD=mysql_xEsdPa +``` + +### 生产环境 (.env.production) +```env +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. 飞书开放平台配置生产环境域名 + +--- + +## 八、调试飞书登录 + +### 开发环境调试 +```bash +# 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 +``` + +### 生产环境测试 +```bash +# 直接访问生产域名 +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、密钥等） + +--- + +## 十、快速参考 + +### 环境判断 + +```typescript +// 前端判断开发/生产环境 +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 地址 + +```typescript +// 开发环境：通过代理访问 +const API_BASE = '/api/v1' + +// 生产环境：同样通过代理访问（OpenResty） +const API_BASE = '/api/v1' +``` + +### 回调地址 + +```typescript +// 开发环境（调试用） +const CALLBACK_URL = 'https://xsm.dev.hnxinyouhe.com/login/callback' + +// 生产环境（正式） +const CALLBACK_URL = 'https://uniservice-mobile.hnxinyouhe.com/login/callback' +``` + +--- + +**最后更新**: 2026-02-28