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 |

---

## 部署目录结构

```
线上服务器:
/www/sites/uniservice-mobile.hnxinyouhe.com/
├── index/                    ← 前端静态文件
│   ├── index.html
│   ├── assets/
│   └── ...
├── log/                      ← 访问日志
│   ├── access.log
│   └── error.log
└── ssl/                      ← SSL 证书
    ├── 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
# 1. 构建前端
cd /www/x-server-mobile/frontend
npm run build

# 2. 执行部署脚本
./deploy/deploy-1panel.sh your-server-ip

# 脚本会提示：
# - 是否需要构建前端（已构建则选 N）
# - 是否需要部署后端
# - 自动重启后端容器
```

### 方式二：手动部署

#### 1. 前端部署

```bash
# 本地构建
cd /www/x-server-mobile/frontend
npm run build

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

#### 2. 后端部署

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

# 在服务器上启动容器
ssh root@your-server
cd /opt/x-server-mobile

# 上传 docker-compose 和环境变量文件
# （从本地复制这些文件）
```

---

## 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;
}

# ============================================
# 飞书登录回调
# ============================================

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 |

---

## 环境变量配置

已创建的文件：`deploy/.env.production`

需要填写的配置：

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

---

## 部署文件清单

| 文件 | 说明 | 用途 |
|------|------|------|
| `deploy/docker-compose.prod.yml` | 后端容器编排 | **线上使用** |
| `deploy/.env.production` | 线上环境变量 | **线上使用** |
| `deploy/nginx-1panel.conf` | Nginx 配置参考 | 1Panel 配置参考 |
| `deploy/deploy-1panel.sh` | 自动部署脚本 | 简化部署流程 |

**注意**：开发和线上配置完全分离，不会互相影响：
- 开发环境使用 `docker-compose.yml`
- 线上环境使用 `deploy/docker-compose.prod.yml`

---

## 验证部署

```bash
# 1. 检查前端
curl -I https://uniservice-mobile.hnxinyouhe.com

# 2. 检查 API
curl https://uniservice-mobile.hnxinyouhe.com/api/v1/user/info \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. 检查后端容器
ssh root@server
docker ps | grep x-server
docker logs -f x-server-backend-prod
```

---

## 常见问题

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

### Q: 后端容器启动失败？
A: 检查 `deploy/docker-compose.prod.yml` 中的数据库和 Redis 容器名称是否正确。

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

---

## 回滚操作

```bash
# 使用备份回滚
ssh root@server
cd /www/sites/uniservice-mobile.hnxinyouhe.com
cp -r backup/YYYYMMDD_HHMMSS/* index/

# 重启后端容器到指定版本
cd /opt/x-server-mobile
git log  # 查看提交历史
git checkout <commit-id>  # 切换到指定版本
docker-compose -f deploy/docker-compose.prod.yml up -d --build
```