xiaoxia-saas/infra/docker/SERVER-DEPLOY.md

服务器部署 - 最佳实践

问题根源

当前主要问题：SSH 长连接不稳定，导致部署命令被 SIGKILL。

解决方案

方案 A：服务器本机执行（推荐）

最稳定的方式，不依赖外部 SSH。

1. 上传部署脚本

# 只需执行一次
scp infra/docker/deploy-control.sh xiaoxia-server:/usr/local/bin/xiaoxia-deploy
ssh xiaoxia-server "chmod +x /usr/local/bin/xiaoxia-deploy"

2. 服务器本机部署

# SSH 进服务器后执行
ssh xiaoxia-server
xiaoxia-deploy staging deploy

或者用 tmux 隔离：

ssh xiaoxia-server
tmux new -s deploy
xiaoxia-deploy staging deploy
# Ctrl+B, D 离开 tmux，部署继续跑

3. 日常操作

# 查看状态
xiaoxia-deploy staging status

# 查看日志
xiaoxia-deploy staging logs api
xiaoxia-deploy staging logs web

# 重启服务
xiaoxia-deploy staging restart web

方案 B：systemd 服务（生产推荐）

让部署变成系统服务，可手动触发或定时执行。

1. 安装服务

scp infra/systemd/xiaoxia-saas-staging-deploy.service xiaoxia-server:/etc/systemd/system/
ssh xiaoxia-server "systemctl daemon-reload"

2. 触发部署

ssh xiaoxia-server "systemctl start xiaoxia-saas-staging-deploy"

3. 查看日志

ssh xiaoxia-server "tail -f /var/lib/xiaoxia-saas-staging/deploy.log"
# 或
ssh xiaoxia-server "journalctl -u xiaoxia-saas-staging-deploy -f"

方案 C：Gitea CI（全自动）

推送代码后自动部署，完全不依赖手工 SSH。

已配置在 .gitea/workflows/deploy.yml，只需：

git push origin main

当前建议

立即执行

1. 把 deploy-control.sh 上传到服务器
2. SSH 进服务器，开 tmux
3. 在 tmux 里执行 xiaoxia-deploy staging deploy
4. 退出 tmux，部署继续跑

稍后优化

1. 配置 systemd 服务
2. 或者启用 Gitea CI 自动部署

为什么不再用本地 SSH 长命令

• SSH 连接不稳定
• 长时间构建容易断
• 重试成本高
• 难以恢复中间状态

服务器本机执行 + tmux/systemd = 最稳定的部署方式。