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

X-Server Mobile 快速部署指南

一、服务器准备

1.1 安装必要软件

# 更新系统
apt-get update && apt-get upgrade -y

# 安装 certbot（SSL 证书）
apt-get install certbot -y

# 安装 rsync（文件同步）
apt-get install rsync -y

1.2 创建部署目录

mkdir -p /opt/x-server-mobile/{frontend,backend,logs,backup}
mkdir -p /opt/x-server-mobile/logs/{backend,nginx}

1.3 获取 SSL 证书

# 停止 OpenResty（如果占用 80 端口）
systemctl stop openresty

# 获取证书
certbot certonly --standalone -d xsm.hnxinyouhe.com

# 重新启动 OpenResty
systemctl start openresty

1.4 准备数据库

# 创建数据库用户
docker exec -it <mysql-container> mysql -uroot -p

# 在 MySQL 中执行：
CREATE USER 'xserver'@'%' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON xserver.* TO 'xserver'@'%';
FLUSH PRIVILEGES;

# 导入数据库（如果有备份）
docker exec -i <mysql-container> mysql -uxserver -pyour_password xserver < backup.sql

---

二、配置文件准备

2.1 环境变量

# 在项目根目录
cp deploy/.env.production.template .env.production

# 编辑填写实际配置
vi .env.production

2.2 更新 docker-compose.prod.yml

# 修改以下配置为实际值：
- DB_HOST=1Panel-mysql-xxxx        # 实际 MySQL 容器名
- DB_PASSWORD=your_password         # 实际密码
- REDIS_HOST=1Panel-redis-xxxx      # 实际 Redis 容器名
- REDIS_PASSWORD=your_redis_password # 实际 Redis 密码

---

三、部署

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

# 1. 构建前端
cd frontend
npm install
npm run build
cd ..

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

# 脚本会自动完成：
# - 备份当前版本
# - 上传前端和后端
# - 重启容器
# - 重载 OpenResty

3.2 方式二：手动部署

# 1. 构建前端
cd frontend && npm run build && cd ..

# 2. 上传前端
rsync -avz --delete frontend/dist/ root@server:/opt/x-server-mobile/frontend/

# 3. 上传后端
rsync -avz --exclude='vendor' --exclude='runtime' backend/ root@server:/opt/x-server-mobile/backend/

# 4. 上传配置文件
scp deploy/docker-compose.prod.yml root@server:/opt/x-server-mobile/
scp deploy/nginx/x-server-mobile-prod.conf root@server:/tmp/

# 5. 登录服务器配置 OpenResty
ssh root@server
cp /tmp/x-server-mobile-prod.conf /usr/local/openresty/nginx/conf/conf.d/x-server-mobile.conf
openresty -t && openresty -s reload

# 6. 启动后端容器
cd /opt/x-server-mobile
docker-compose -f docker-compose.prod.yml up -d

---

四、验证部署

4.1 检查容器状态

docker ps | grep x-server
docker logs -f x-server-backend-prod

4.2 检查服务

# 检查前端
curl -I https://xsm.hnxinyouhe.com

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

4.3 功能测试

• 登录页面正常访问
• 邮箱密码登录成功
• 飞书免登成功
• 审批列表正常显示
• 飞书卡片通知正常

---

五、常见问题

Q1: 容器无法启动

# 查看详细日志
docker logs x-server-backend-prod

# 检查网络
docker network ls | grep 1panel
docker network inspect 1panel-network

# 检查环境变量
docker exec x-server-backend-prod env | grep DB_

Q2: API 返回 500

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

# 检查数据库连接
docker exec x-server-backend-prod php -r "
var_dump(getenv('DB_HOST'));
var_dump(getenv('DB_DATABASE'));
"

# 进入容器调试
docker exec -it x-server-backend-prod bash

Q3: SSL 证书问题

# 检查证书路径
ls -la /etc/letsencrypt/live/xsm.hnxinyouhe.com/

# 测试证书
openssl s_client -connect xsm.hnxinyouhe.com:443 -servername xsm.hnxinyouhe.com

# 手动续期
certbot renew --force-renewal

Q4: 前端刷新 404

检查 OpenResty 配置中的 try_files 指令：

location / {
    root /opt/x-server-mobile/frontend;
    try_files $uri $uri/ /index.html;  # 确保有这行
}

---

六、回滚

# 查看可用备份
ssh root@server "ls -la /opt/x-server-mobile/backup/"

# 执行回滚
./scripts/rollback.sh 20240227_150000

---

七、监控命令

# 实时日志
docker logs -f x-server-backend-prod

# 容器资源
docker stats x-server-backend-prod

# Nginx 访问日志
tail -f /opt/x-server-mobile/logs/nginx_access.log

# Nginx 错误日志
tail -f /opt/x-server-mobile/logs/nginx_error.log

---

八、更新部署

当代码有更新时：

# 1. 拉取最新代码
git pull

# 2. 构建前端
cd frontend && npm run build && cd ..

# 3. 部署
./scripts/deploy.sh your-server-ip

---

配置检查清单

部署前确认：

# 1. 检查环境变量
cat .env.production | grep -v "^#" | grep -v "^$"

# 2. 检查构建产物
ls -la frontend/dist/

# 3. 检查 OpenResty 配置
cat deploy/nginx/x-server-mobile-prod.conf | grep server_name

# 4. 测试 SSH 连接
ssh root@your-server "echo 'SSH OK'"

---

联系支持

如有问题，请参考完整文档：

• DEPLOYMENT.md - 完整部署文档
• DEPLOYMENT_CHECKLIST.md - 部署检查清单
• PROJECT_ISSUES.md - 问题汇总