piano-plan/docs/DEPLOYMENT.md

部署指南

目标服务器

• 服务器: 阿里云 ECS (CentOS 7)
• IP: 47.106.65.108
• 连接: ssh -i ~/.ssh/id_rsa root@47.106.65.108

---

部署架构

┌─────────────────────────────┐
│      阿里云 ECS (CentOS 7)   │
│                             │
│   ┌─────────────────────┐   │
│   │  Docker Container   │   │
│   │   piano-plan:5000   │   │
│   └─────────────────────┘   │
│          ▲   │               │
│          │   │               │
│   ┌──────┴───┴──────────┐   │
│   │  数据卷 (宿主机目录)   │   │
│   │  /data               │   │
│   │  /output             │   │
│   │  /config             │   │
│   └──────────────────────┘   │
└─────────────────────────────┘

---

数据分离（关键）

目录	容器内	宿主机	说明
数据库	/app/data	./data	SQLite数据库
PDF输出	/app/output	./output	导出的PDF
API配置	/app/config	./config	LLM配置

优势:

• 容器删除重建，数据不丢失
• 备份只需备份宿主机目录

---

部署步骤

1. 上传代码

# 在本地打包
cd projects/青年钢琴集体课/练习方案系统
tar -czvf piano-plan.tar.gz \
  --exclude=venv \
  --exclude=__pycache__ \
  --exclude=.git \
  -f - .

# 上传到服务器
scp -i ~/.ssh/id_rsa piano-plan.tar.gz root@47.106.65.108:/opt/

# SSH登录服务器
ssh -i ~/.ssh/id_rsa root@47.106.65.108

2. 服务器准备

# 安装 Docker（如果未安装）
curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

# 安装 docker-compose（CentOS 7）
curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

cd /opt
mkdir -p piano-plan && cd piano-plan
tar -xzf ../piano-plan.tar.gz --strip-components=1

# 创建数据目录
mkdir -p data output config

# 开放端口
firewall-cmd --permanent --add-port=5000/tcp
firewall-cmd --reload

3. 启动容器

# 方式一：使用 docker-compose（推荐）
docker-compose up -d --build

# 方式二：手动 docker run
docker build -t piano-plan .
docker run -d \
  --name piano-plan \
  -p 5000:5000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/config:/app/config \
  -e FLASK_ENV=production \
  piano-plan

4. 验证部署

# 检查容器状态
docker ps | grep piano-plan

# 检查日志
docker logs piano-plan

# 访问测试
curl http://localhost:5000/

5. 配置防火墙

# 开放5000端口（如果需要）
firewall-cmd --permanent --add-port=5000/tcp
firewall-cmd --reload

6. 配置 Nginx 反向代理（可选）

server {
    listen 80;
    server_name piano.yourdomain.com;  # 替换为实际域名

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

---

备份与恢复

备份

# 停止服务
docker-compose stop

# 打包数据
tar -czvf piano-plan-backup-$(date +%Y%m%d).tar.gz data/ output/ config/

# 重启服务
docker-compose start

恢复

# 停止服务
docker-compose stop

# 解压备份
tar -xzf piano-plan-backup-20260418.tar.gz

# 重启服务
docker-compose start

---

更新部署

# 拉取新代码（方式一：git pull）
git pull

# 或 上传新代码（方式二）
# 重复"上传代码"步骤

# 重新构建并启动
docker-compose up -d --build

# 数据不会丢失（挂载卷）

---

常用命令

# 查看日志
docker logs -f piano-plan

# 重启服务
docker-compose restart

# 停止服务
docker-compose stop

# 删除容器（数据不丢失）
docker-compose down

# 完全删除（包括镜像）
docker-compose down --rmi local

---

故障排查

容器启动失败

# 查看日志
docker logs piano-plan

# 检查端口
netstat -tlnp | grep 5000

数据库问题

# 进入容器检查
docker exec -it piano-plan sh

# 检查数据目录
ls -la /app/data/

---

版本信息

日期	版本	说明
2026-04-18	V1.2	初始部署版本，含用户/角色/班级管理

---

联系

部署完成后访问: http://47.106.65.108:5000