asd-backend/docs/SERVER-MIGRATION-PLAN.md

服务器迁移计划

新旧对比

项目	旧服务器 (1panel-server)	新服务器 (xxx.xxx.xxx.xxx)
系统	-	待填写
CPU	-	待填写
内存	-	待填写
磁盘	-	待填写
区域	-	成都
角色	当前生产+开发	目标生产+开发

阶段 1 — 基础设施安装

1.1 安装 Docker

apt update && apt install -y docker.io docker-compose-v2

1.2 启动 PostgreSQL

docker run -d --name postgres \
  --network host \
  -e POSTGRES_PASSWORD=password \
  -v /var/lib/postgresql/data:/var/lib/postgresql/data \
  postgres:17.6-alpine

创建数据库：milkydata、milkydata_dev

1.3 从旧服务器迁移数据库

# 旧服务器导出
pg_dump -Fc milkydata > /tmp/milkydata.dump
# 新服务器导入
pg_restore -d milkydata /tmp/milkydata.dump

1.4 安装并配置 nginx

apt install -y nginx

复制 nginx 配置文件和 SSL 证书。

1.5 复制 SSL 证书 + nginx 配置

rsync -av root@old-server:/etc/nginx/sites-available/ /etc/nginx/sites-available/
rsync -av root@old-server:/etc/nginx/sites-enabled/ /etc/nginx/sites-enabled/
rsync -av root@old-server:/etc/ssl/ /etc/ssl/

阶段 2 — 后端部署

2.1 创建 systemd 服务（blue/green/dev）

mkdir -p /root/rust/rust_backend_blue
mkdir -p /root/rust/rust_backend_green
mkdir -p /root/rust/rust_backend_dev

2.2 部署 Rust 后端

cd ASD-backend/rust-backend
deploy.sh development --remote-host xxx.xxx.xxx.xxx
deploy.sh production --remote-host xxx.xxx.xxx.xxx

2.3 更新 deploy.sh

将默认 REMOTE_HOST 改为新服务器 IP。

阶段 3 — ⚠️ 关键配置（迁移后必做）

3.1 设置 APP_BASE_URL

每个环境的 .env 文件必须设置 APP_BASE_URL，否则默认值为 https://dev.xmclassmate.top，导致支付宝通知回调发错服务器。

# 生产环境
echo "APP_BASE_URL=https://xmclassmate.top" >> /root/rust/rust_backend_blue/.env
echo "APP_BASE_URL=https://xmclassmate.top" >> /root/rust/rust_backend_green/.env

# 开发环境
echo "APP_BASE_URL=https://dev.xmclassmate.top" >> /root/rust/rust_backend_dev/.env

3.2 验证 notify_url

迁移后通过 API 检查支付表单的 notify_url 是否正确：

# 获取访客 JWT
JWT=$(curl -s -X POST 'https://YOUR_DOMAIN/api/guest-login' | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# 检查支付表单的 notify_url
curl -s "https://YOUR_DOMAIN/payment/page?package=monthly&jwt=${JWT}" | grep -oP 'notify_url[^"]+"[^"]+' | head -1

预期输出：notify_url" value="https://YOUR_DOMAIN/payment/notify"

3.3 验证支付宝密钥匹配

# 确认密钥配置正确（生产用正式密钥，开发用沙箱密钥）
ssh root@NEW_SERVER 'grep "ALIPAY_APP_ID\|ALIPAY_GATEWAY" /root/rust/rust_backend_*/env'

环境	APP_ID 前缀	GATEWAY
生产	202100...	openapi.alipay.com
开发	902100...（沙箱）	openapi-sandbox.dl.alipaydev.com

3.4 验证关键端点

# 支付页面可访问（非 503）
curl -s -o /dev/null -w "%{http_code}" https://YOUR_DOMAIN/payment

# 访客登录正常
curl -s -X POST https://YOUR_DOMAIN/api/guest-login | python3 -c "import sys,json; print(json.load(sys.stdin).get('success','FAIL'))"

# 健康检查
curl -s https://YOUR_DOMAIN/health | python3 -c "import sys,json; print(json.load(sys.stdin).get('status','FAIL'))"

3.5 迁移后支付全链路测试

bash tests/payment_e2e_test.sh

3.6 运行部署后测试

export TEST_DOMAIN="https://YOUR_DOMAIN"
./deploy.sh production --skip-tests=false
# 或手动运行
export BASE_URL="https://YOUR_DOMAIN"
bash lib/test.sh

阶段 4 — DNS 切换

4.1 更新 DNS 记录

将域名指向新服务器 IP。

4.2 验证公网访问

curl https://dev.xmclassmate.top/health
curl https://xmclassmate.top/health
curl https://xmclassmate.top/payment

阶段 5 — 清理

• 迁移 GlitchTip (Sentry)
• 旧服务器保留 1 周作为回退
• 确认无问题后关闭旧服务器

迁移检查清单

#	检查项	命令/方法	状态
1	PostgreSQL 运行	docker ps | grep postgres	⬜
2	数据库导入	pg_restore -d milkydata /tmp/xxx.dump	⬜
3	nginx 配置正确	nginx -t	⬜
4	SSL 证书有效	openssl s_client -connect DOMAIN:443	⬜
5	后端服务运行	systemctl status rust-backend-*	⬜
6	APP_BASE_URL 已设置	grep APP_BASE_URL /root/rust/rust_backend_*/.env	⬜
7	支付宝密钥环境正确	grep ALIPAY_APP_ID /root/rust/rust_backend_*/.env	⬜
8	notify_url 正确	见 3.2 验证	⬜
9	支付页面可访问	curl DOMAIN/payment	⬜
10	访客登录正常	curl -X POST DOMAIN/api/guest-login	⬜
11	全链路测试通过	bash tests/payment_e2e_test.sh	⬜
12	部署后测试通过	deploy.sh production	⬜

历史问题复盘

日期	问题	根因	预防
2026-07-23	支付回调丢失	APP_BASE_URL 未设置，默认指向 dev.xmclassmate.top，开发服务器无法通过 RSA2 验证	迁移清单第 6、8 项确保 base_url 配置正确
2026-07-18	保存功能 500	nginx AppArmor 缺少 /var/lib/nginx/** rw	部署后测试 test_nginx_proxy_temp
2026-07-13	ICP 备案号未显示	nginx 配置路径不匹配（/www/sites/ vs /etc/nginx/sites-enabled/）	迁移清单第 3 项检查 nginx 配置