x-server-mobile/docs/DEPLOY_ONLINE_GUIDE.md

# uniservice-mobile.hnxinyouhe.com 线上部署说明

## 线上环境信息

| 项目 | 值 |
|------|-----|
| **域名** | uniservice-mobile.hnxinyouhe.com |
| **网站根目录** | /www/sites/uniservice-mobile.hnxinyouhe.com/index |
| **后端端口** | 8787 |
| **MySQL 容器** | 1Panel-mysql-XyxS |
| **Redis 容器** | 1Panel-redis-pxdb |
| **Docker 网络** | 1panel-network |

---

## 部署架构说明

**重要：前后端分离部署**

| 组件 | 部署位置 | 部署方式 |
|------|---------|---------|
| **前端** | 1Panel 静态站点 | 本地打包 → 上传静态文件 |
| **后端** | Docker 容器 | 上传代码 → 容器运行 |

### 为什么前端要本地打包？

1. **服务器不需要 Node.js** - 只需 Nginx 托管静态文件
2. **打包速度快** - 本地开发机性能通常更好
3. **节省服务器资源** - 不占用服务器 CPU/内存编译
4. **避免环境问题** - 本地打包更稳定可靠

---

## 部署目录结构

```
线上服务器:

/www/sites/uniservice-mobile.hnxinyouhe.com/
├── index/                    ← 前端静态文件（本地打包后上传）
│   ├── index.html
│   ├── assets/
│   └── ...
├── log/                      ← 访问日志
│   ├── access.log
│   └── error.log
└── ssl/                      ← SSL 证书（1Panel 管理）
    ├── fullchain.pem
    └── privkey.pem

/opt/x-server-mobile/              ← 后端部署目录
├── backend/                   ← 后端代码
│   ├── app/
│   ├── vendor/
│   └── ...
├── deploy/                    ← 部署配置文件
│   ├── docker-compose.prod.yml
│   ├── .env.production
│   ├── nginx-1panel.conf
│   └── deploy-1panel.sh
└── logs/                      ← 后端日志
    └── backend/
```

---

## 快速部署步骤

### 第一步：本地打包前端（开发机执行）

```bash
# 在开发机本地执行
cd /www/x-server-mobile/frontend

# 安装依赖（首次或依赖变化时）
npm install

# 构建生产版本
npm run build

# 构建完成后，静态文件在 frontend/dist/ 目录
ls frontend/dist/
# 输出: index.html, assets/, ...
```

### 第二步：上传到服务器

```bash
# 上传前端静态文件到服务器
rsync -avz --delete frontend/dist/* root@your-server:/www/sites/uniservice-mobile.hnxinyouhe.com/index/

# 或使用 scp
scp -r frontend/dist/* root@your-server:/www/sites/uniservice-mobile.hnxinyouhe.com/index/
```

### 第三步：上传后端代码

```bash
# 上传后端代码到服务器
rsync -avz --exclude='vendor' --exclude='runtime' backend/ root@your-server:/opt/x-server-mobile/backend/
```

### 第四步：配置 1Panel Nginx

在 1Panel 面板中配置反向代理（详见下方 Nginx 配置章节）

### 第五步：启动后端容器

```bash
# 在服务器上执行
ssh root@your-server
cd /opt/x-server-mobile

# 确保配置文件已上传
ls deploy/docker-compose.prod.yml
ls deploy/.env.production

# 启动后端容器
docker-compose -f deploy/docker-compose.prod.yml up -d

# 查看容器状态
docker ps | grep x-server
docker logs -f x-server-backend-prod
```

---

## 1Panel Nginx 配置

### 配置位置
1Panel 面板 → 网站 → 找到 `uniservice-mobile.hnxinyouhe.com` → 配置文件

### 需要添加的反向代理规则

将以下内容添加到现有的 `server {}` 配置块中（在 `root` 指令之前）：

```nginx
# ============================================
# 后端 API 反向代理
# ============================================

location /api/ {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

# ============================================
# 飞书登录回调（必须在 API 之前匹配）
# ============================================

location /login {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

location /login/callback {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

location /login/qrcode {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

# 飞书卡片回调
location /feishu/card/callback {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

# ============================================
# 静态资源缓存（可选，提升性能）
# ============================================

location ~* \.(js|css|png|jpg|jpeg|gif|webp|svg|ico|woff|woff2|ttf|eot)$ {
    root /www/sites/uniservice-mobile.hnxinyouhe.com/index;
    expires 7d;
    add_header Cache-Control "public, immutable";
    access_log off;
}
```

### 配置说明

| 路径 | 说明 |
|------|------|
| `/api/*` | 后端 API 接口，代理到 8787 端口 |
| `/login/*` | 飞书登录回调，代理到后端 |
| `/feishu/card/callback` | 飞书卡片回调，代理到后端 |
| 静态资源 | js/css/images 等，缓存 7 天（可选） |
| 根路径 `/` | SPA 路由，返回 index.html |

**重要**：
- 反向代理规则要放在 `root` 指令**之前**
- 静态资源缓存规则要放在反向代理之前（优先匹配）

---

## 环境变量配置

### 飞书配置（必须配置）

编辑 `deploy/.env.production`，填写飞书应用配置：

```env
# 飞书配置（必须配置）
FEISHU_APP_ID=cli_axxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxx
```

### 数据库和 Redis 配置

已预先配置好线上环境，无需修改：

```env
# 数据库（已配置）
DB_HOST=1Panel-mysql-XyxS
DB_PORT=3306
DB_DATABASE=xserver
DB_USERNAME=xserver
DB_PASSWORD=NsNBSQm4b2b7SzhR

# Redis（已配置）
REDIS_HOST=1Panel-redis-pxdb
REDIS_PORT=6379
REDIS_PASSWORD=redis_FTzdM6
```

---

## 使用部署脚本（可选）

如需自动化部署，可以使用部署脚本：

```bash
./deploy/deploy-1panel.sh your-server-ip
```

脚本功能：
- 自动上传前端静态文件
- 自动上传后端代码
- 自动重启后端容器

**注意**：使用脚本前需要先在本地执行 `npm run build` 打包前端。

---

## 部署验证

### 1. 检查前端

```bash
# 检查首页是否可访问
curl -I https://uniservice-mobile.hnxinyouhe.com

# 应该返回 200 OK
```

### 2. 检查 API

```bash
# 检查 API 是否正常（需要有效的 token）
curl https://uniservice-mobile.hnxinyouhe.com/api/v1/user/info \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 3. 检查后端容器

```bash
ssh root@your-server
docker ps | grep x-server
# 应该看到 x-server-backend-prod 容器

docker logs -f x-server-backend-prod
# 查看后端日志
```

### 4. 检查 Nginx 日志

```bash
# 在 1Panel 面板中查看
# 或者直接查看日志文件
tail -f /www/sites/uniservice-mobile.hnxinyouhe.com/log/access.log
```

---

## 常见问题

### Q1: 前端显示但 API 调用 404？
**A**: 检查 1Panel Nginx 配置中是否添加了 `/api/` 的反向代理规则。

### Q2: 后端容器启动失败？
**A**: 检查：
- 数据库和 Redis 容器是否运行
- Docker 网络 `1panel-network` 是否存在
- 容器日志：`docker logs x-server-backend-prod`

### Q3: 飞书登录失败？
**A**: 检查 `/login/*` 的反向代理规则是否已添加。

### Q4: 静态资源加载 404？
**A**: 确认前端上传到了正确的目录：`/www/sites/uniservice-mobile.hnxinyouhe.com/index/`

### Q5: 前端页面空白？
**A**: 检查：
- 确认前端打包成功：`ls frontend/dist/` 是否有 `index.html`
- 检查浏览器控制台是否有错误

---

## 开发环境 vs 生产环境

| 项目 | 开发环境 | 生产环境 |
|------|---------|---------|
| **前端** | `npm run dev` (Vite 开发服务器) | `npm run build` + 上传静态文件 |
| **后端** | `docker-compose.yml` | `deploy/docker-compose.prod.yml` |
| **API 地址** | `http://localhost:8787/api/v1` | `/api/v1` (相对路径) |
| **数据** | 本地数据库或开发数据库 | 线上数据库 |

---

## 回滚操作

### 前端回滚

```bash
# 从之前的备份恢复
ssh root@your-server
cp -r /www/sites/uniservice-mobile.hnxinyouhe.com/backup/YYYYMMDD_HHMMSS/* \
      /www/sites/uniservice-mobile.hnxinyouhe.com/index/
```

### 后端回滚

```bash
ssh root@your-server
cd /opt/x-server-mobile

# 切换到之前的提交
git log --oneline
git checkout <commit-id>

# 重新构建并启动
docker-compose -f deploy/docker-compose.prod.yml up -d --build
```

---

## 文件清单

部署相关的所有文件：

| 文件 | 用途 |
|------|------|
| `deploy/docker-compose.prod.yml` | 线上后端容器配置 |
| `deploy/.env.production` | 线上环境变量 |
| `deploy/nginx-1panel.conf` | Nginx 配置参考 |
| `deploy/deploy-1panel.sh` | 自动部署脚本 |
| `docs/DEPLOY_ONLINE_GUIDE.md` | 本文档 |

**注意**：
- 开发环境配置（`docker-compose.yml`）与线上环境完全分离
- 部署文件都在 `deploy/` 目录，不会影响开发环境配置