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/

---

快速部署步骤

方式一：使用部署脚本（推荐）

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

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

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

方式二：手动部署

1. 前端部署

# 本地构建
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. 后端部署

# 上传后端代码
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 指令之前）：

# ============================================
# 后端 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

需要填写的配置：

# 飞书配置（必须配置）
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

---

验证部署

# 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/* 的反向代理规则是否已添加。

---

回滚操作

# 使用备份回滚
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