newapi-yx-diy/.claude/commands/migrate-server.md

Migrate Server - 服务器迁移指南

帮助将 new-api 服务从老服务器迁移到新服务器，包括代码部署、数据库迁移和配置同步。

执行步骤

1. 收集信息

先向用户确认以下信息：

• 老服务器 IP / 访问方式
• 新服务器 IP / 访问方式
• 当前使用的数据库类型（SQLite / MySQL / PostgreSQL）
• 当前部署方式（Docker Compose / 直接部署）
• 是否使用 Redis
• 是否有自定义域名需要迁移

2. 老服务器 - 备份数据

2.1 数据库备份

如果使用 SQLite：

# 找到 SQLite 数据库文件（通常在项目根目录或 data/ 目录下）
# 停止服务防止写入
docker compose stop  # 或 systemctl stop new-api

# 复制数据库文件
cp /path/to/new-api.db /backup/new-api.db

# 或者使用 sqlite3 导出
sqlite3 /path/to/new-api.db .dump > /backup/new-api-dump.sql

如果使用 MySQL：

# 导出完整数据库
mysqldump -u root -p --single-transaction --routines --triggers new_api > /backup/new-api-mysql.sql

# 或者如果 MySQL 在 Docker 中
docker exec <mysql_container> mysqldump -u root -p<password> new_api > /backup/new-api-mysql.sql

如果使用 PostgreSQL：

# 导出完整数据库
pg_dump -U postgres -d new_api -F c -f /backup/new-api-pg.dump

# 或者如果在 Docker 中
docker exec <pg_container> pg_dump -U postgres -d new_api -F c > /backup/new-api-pg.dump

2.2 配置备份

# 备份环境变量文件
cp .env /backup/.env

# 备份 Docker Compose 配置
cp docker-compose.yml /backup/docker-compose.yml

# 备份其他配置文件（如果有）
cp -r config/ /backup/config/ 2>/dev/null

2.3 Redis 数据备份（如果使用）

# Redis 数据通常不需要迁移（缓存会自动重建）
# 但如果需要：
redis-cli BGSAVE
cp /var/lib/redis/dump.rdb /backup/redis-dump.rdb

3. 传输备份到新服务器

# 使用 scp 传输
scp -r /backup/ user@new-server:/path/to/backup/

# 或使用 rsync
rsync -avz /backup/ user@new-server:/path/to/backup/

4. 新服务器 - 部署准备

4.1 安装基础环境

# Docker + Docker Compose（推荐）
curl -fsSL https://get.docker.com | sh
apt install docker-compose-plugin  # 或 docker compose v2

# 或者直接部署需要 Go 1.22+ 和 Node.js/Bun

4.2 拉取代码

git clone https://git.586vip.cn/huangzhenpc/newapi-yx-diy.git
cd newapi-yx-diy
git checkout dev-v0.11.0-alpha.9  # 或目标分支

4.3 恢复配置

# 恢复环境变量
cp /path/to/backup/.env .env

# 恢复 Docker Compose 配置（如有定制）
cp /path/to/backup/docker-compose.yml docker-compose.yml

5. 新服务器 - 恢复数据库

如果使用 SQLite：

# 直接复制数据库文件到项目目录
cp /path/to/backup/new-api.db ./data/new-api.db
# GORM AutoMigrate 会在启动时自动添加新字段（如 Phone）

如果使用 MySQL：

# 先启动 MySQL 容器
docker compose up -d mysql

# 等待 MySQL 完全启动
sleep 10

# 导入数据
docker exec -i <mysql_container> mysql -u root -p<password> new_api < /path/to/backup/new-api-mysql.sql

如果使用 PostgreSQL：

# 先启动 PostgreSQL 容器
docker compose up -d postgres

# 等待 PostgreSQL 完全启动
sleep 5

# 创建数据库（如果不存在）
docker exec <pg_container> createdb -U postgres new_api

# 导入数据
docker exec -i <pg_container> pg_restore -U postgres -d new_api < /path/to/backup/new-api-pg.dump

6. 新服务器 - 启动服务

# Docker Compose 部署
docker compose up -d

# 检查服务状态
docker compose ps
docker compose logs -f --tail=50

7. 验证

向用户确认以下检查项：

• 服务是否正常启动（访问 /api/status）
• 管理员账号能否正常登录
• 用户数据是否完整
• 渠道配置是否正常
• API 密钥是否可用
• 如果有自定义域名，DNS 是否已切换

8. 切换流量

• 更新 DNS 记录指向新服务器
• 或更新反向代理（Nginx/Caddy）配置
• 老服务器保留一段时间作为回退方案

注意事项

1. GORM AutoMigrate：新版本可能有新的数据库字段（如 phone），启动时 GORM 会自动添加，不需要手动执行迁移脚本
2. 环境变量：确保 .env 中的数据库连接字符串指向正确的地址
3. 数据一致性：迁移前停止老服务器的写入，避免数据不一致
4. Redis：Redis 缓存数据不需要迁移，服务启动后会自动重建
5. 密钥安全：传输过程中注意保护敏感信息（数据库密码、API 密钥等）
6. 回退方案：保留老服务器至少 1 周，确认新服务器稳定后再关闭