xinyouhe/x-server-mobile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5f110b6988dc0f64ab139191385e6ddd862bb323
x-server-mobile/docs/DEPLOY_ONLINE_GUIDE.md
T
root 5f110b6988 docs: 明确前端本地打包部署流程，优化部署脚本 
更新内容：
- DEPLOY_ONLINE_GUIDE.md: 详细说明前端本地打包的优势和流程
- deploy-1panel.sh: 优化部署脚本，添加前端构建验证
- 强调前后端分离部署的架构差异

核心变更：
1. 明确说明前端必须本地打包（npm run build）
2. 上传的是打包后的静态文件，不需要服务器 Node.js
3. 添加前端构建验证步骤
4. 优化部署流程提示和输出

部署流程：
- 本地：前端构建 → 验证构建 → 上传静态文件
- 服务器：后端代码 → Docker 容器运行
- 1Panel：Nginx 托管静态文件 + 反向代理后端 API

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 18:24:42 +08:00

9.8 KiB
Raw Blame History

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/

快速部署步骤

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

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

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

# 构建生产版本
npm run build

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

第二步：上传到服务器

# 上传前端静态文件到服务器
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/

第三步：上传后端代码

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

第四步：配置 1Panel Nginx

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

第五步：启动后端容器

# 在服务器上执行
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 指令之前）：

# ============================================
# 后端 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，填写飞书应用配置：

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

数据库和 Redis 配置

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

# 数据库（已配置）
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

使用部署脚本（可选）

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

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

脚本功能：

  • 自动上传前端静态文件
  • 自动上传后端代码
  • 自动重启后端容器

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

部署验证

1. 检查前端

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

# 应该返回 200 OK

2. 检查 API

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

3. 检查后端容器

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

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

4. 检查 Nginx 日志

# 在 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 (相对路径)
数据 本地数据库或开发数据库 线上数据库

回滚操作

前端回滚

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

后端回滚

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/ 目录，不会影响开发环境配置
Reference in New Issue View Git Blame Copy Permalink