root
258 lines
7.6 KiB
Markdown
258 lines
7.6 KiB
Markdown
# 环境配置说明
|
||
|
||
本文档说明开发环境和生产环境的区别，避免混淆。
|
||
|
||
---
|
||
|
||
## 一、环境对比
|
||
|
||
| 项目 | 开发环境 | 生产环境 |
|
||
|------|----------|----------|
|
||
| **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
|