x-server-mobile/docs/guides/DEPLOY_ONLINE_GUIDE.md

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

## 线上环境信息

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

---

## 部署架构

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

---

## 目录结构

```
/opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/
├── index.html              # 前端入口
├── assets/                 # 前端静态资源
└── server/                 # 整个项目（Git 仓库）
    ├── backend/            # 后端代码
    │   ├── app/
    │   ├── config/
    │   └── ...
    ├── deploy/             # 部署配置
    │   ├── docker-compose.prod.yml
    │   ├── .env.production
    │   └── deploy.sh
    ├── frontend/           # 前端源码（不使用）
    ├── docs/               # 文档
    └── logs/               # 日志
        └── backend/
```

---

## 快速部署

### 前端部署（本地）

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

# 上传静态文件
rsync -avz --delete \
    frontend/dist/ \
    root@45.153.130.80:/opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/
```

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

```bash
# 登录服务器
ssh root@45.153.130.80
cd /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server

# 拉取代码
git pull origin master

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

或使用部署脚本：
```bash
ssh root@45.153.130.80
cd /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server
./deploy/deploy.sh
```

---

## 首次部署

### 1. 克隆后端代码

```bash
ssh root@45.153.130.80
cd /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index

# 克隆 master 分支
git clone <your-git-repository-url> server
cd server
git checkout master
```

### 2. 上传 Dockerfile

```bash
# 本地执行
scp backend/Dockerfile.prod root@45.153.130.80:/opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server/backend/
```

### 3. 配置环境变量

```bash
ssh root@45.153.130.80
vi /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server/deploy/.env.production
```

填写飞书配置：

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

### 4. 创建日志目录

```bash
ssh root@45.153.130.80
mkdir -p /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server/logs/backend
```

### 5. 上传部署脚本

```bash
# 本地执行
scp deploy/server-deploy.sh root@45.153.130.80:/opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server/deploy/deploy.sh

# 赋予执行权限
ssh root@45.153.130.80
chmod +x /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server/deploy/deploy.sh
```

### 6. 启动后端容器

```bash
ssh root@45.153.130.80
cd /opt/1panel/www/sites/uniservice-mobile.hnxinyouhe.com/index/server
docker-compose -f deploy/docker-compose.prod.yml up -d
docker ps | grep x-server
```

### 7. 上传前端

```bash
cd /www/x-server-mobile/frontend
npm run build
rsync -avz --delete \
    frontend/dist/ \
    root@45.153.130.80:/opt/1panel/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@45.153.130.80
docker ps | grep x-server
docker logs -f x-server-backend-prod
```

---

## 常见问题

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

---

## 文件清单

需要上传到服务器的文件：

| 文件 | 目标位置 |
|------|---------|
| `backend/Dockerfile.prod` | `server/backend/` |
| `deploy/docker-compose.prod.yml` | `server/deploy/` |
| `deploy/.env.production` | `server/deploy/` |
| `deploy/server-deploy.sh` | `server/deploy/deploy.sh` |