x-server-mobile/docs/DEPLOY_ONLINE_GUIDE.md

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

## 线上环境信息

| 项目 | 值 |
|------|-----|
| **域名** | uniservice-mobile.hnxinyouhe.com |
| **前端目录** | /www/sites/uniservice-mobile.hnxinyouhe.com/index |
| **后端目录** | /opt/x-server-mobile |
| **后端容器** | x-server-backend-prod (端口 8787) |
| **MySQL 容器** | 1Panel-mysql-XyxS |
| **Redis 容器** | 1Panel-redis-pxdb |
| **Docker 网络** | 1panel-network |

---

## 部署架构

| 组件 | 部署方式 |
|------|---------|
| **前端** | 本地构建 → 上传静态文件 |
| **后端** | Git 拉取 → Docker 重启 |

---

## 快速部署

### 方式一：自动部署脚本（推荐）

**本地执行**（前端+后端一起部署）：

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

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

脚本会自动：
- 上传前端静态文件到 1Panel 静态站点
- 上传后端代码到服务器
- 重启后端 Docker 容器

### 方式二：手动部署

#### 前端部署（本地）

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

#### 后端部署（服务器）

```bash
# 登录服务器
ssh root@your-server
cd /opt/x-server-mobile

# 拉取代码
git pull

# 重启容器
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d
```

---

## 服务器端部署脚本

在服务器上创建 `/opt/x-server-mobile/deploy.sh`：

```bash
#!/bin/bash
cd /opt/x-server-mobile
git pull
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d
docker ps | grep x-server
```

使用：

```bash
ssh root@your-server
cd /opt/x-server-mobile
chmod +x deploy.sh
./deploy.sh
```

---

## 首次部署

### 1. 服务器准备

```bash
ssh root@your-server

# 创建项目目录
mkdir -p /opt/x-server-mobile
cd /opt/x-server-mobile

# 克隆代码
git clone <your-git-repository-url> .

# 上传部署配置
# （在本地执行）
scp deploy/docker-compose.prod.yml root@your-server:/opt/x-server-mobile/
scp deploy/.env.production root@your-server:/opt/x-server-mobile/
```

### 2. 配置环境变量

```bash
ssh root@your-server
vi /opt/x-server-mobile/.env.production
```

填写飞书配置：

```env
FEISHU_APP_ID=cli_axxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxx
```

### 3. 启动后端容器

```bash
ssh root@your-server
cd /opt/x-server-mobile
docker-compose -f docker-compose.prod.yml up -d
docker ps | grep x-server
```

### 4. 配置 1Panel 静态站点

1. 在 1Panel 面板创建静态网站
2. 根目录: `/www/sites/uniservice-mobile.hnxinyouhe.com/index`
3. 添加 Nginx 反向代理（见下方配置）

### 5. 上传前端

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

---

## 1Panel Nginx 配置

在 1Panel 面板（网站设置 → 配置文件）添加反向代理：

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

# 飞书登录回调
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;
}
```

---

## 部署验证

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

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

---

## 常见问题

| 问题 | 解决方案 |
|------|---------|
| API 404 | 检查 Nginx 反向代理配置 |
| 容器启动失败 | 检查数据库/Redis 容器状态，查看日志 |
| 飙书登录失败 | 检查 `/login/*` 反向代理配置 |
| 静态资源 404 | 确认前端上传到正确目录 |

---

## 文件清单

| 文件 | 用途 |
|------|------|
| `deploy/docker-compose.prod.yml` | 生产环境 Docker Compose |
| `deploy/.env.production` | 生产环境变量 |
| `deploy/nginx-1panel.conf` | Nginx 配置参考 |
| `deploy/deploy-1panel.sh` | 本端部署脚本 |
| `deploy/server-deploy.sh` | 服务器端部署脚本 |