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                          │
└───────────────────────────┬─────────────────────────────────┘
                            │ 重新构建部署
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   生产环境更新完成                            │
└─────────────────────────────────────────────────────────────┘
```

### 日常开发命令

```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