feat: 初始提交 v1.2.0 - 钢琴练习方案生成系统

2026-04-21 20:00:33 +08:00
commit fd593bddf4
44 changed files with 10936 additions and 0 deletions
@@ -0,0 +1,250 @@
+# 部署指南
+
+## 目标服务器
+
+- **服务器**: 阿里云 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. 上传代码
+
+```bash
+# 在本地打包
+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. 服务器准备
+
+```bash
+# 安装 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. 启动容器
+
+```bash
+# 方式一：使用 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. 验证部署
+
+```bash
+# 检查容器状态
+docker ps | grep piano-plan
+
+# 检查日志
+docker logs piano-plan
+
+# 访问测试
+curl http://localhost:5000/
+```
+
+### 5. 配置防火墙
+
+```bash
+# 开放5000端口（如果需要）
+firewall-cmd --permanent --add-port=5000/tcp
+firewall-cmd --reload
+```
+
+### 6. 配置 Nginx 反向代理（可选）
+
+```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;
+    }
+}
+```
+
+---
+
+## 备份与恢复
+
+### 备份
+
+```bash
+# 停止服务
+docker-compose stop
+
+# 打包数据
+tar -czvf piano-plan-backup-$(date +%Y%m%d).tar.gz data/ output/ config/
+
+# 重启服务
+docker-compose start
+```
+
+### 恢复
+
+```bash
+# 停止服务
+docker-compose stop
+
+# 解压备份
+tar -xzf piano-plan-backup-20260418.tar.gz
+
+# 重启服务
+docker-compose start
+```
+
+---
+
+## 更新部署
+
+```bash
+# 拉取新代码（方式一：git pull）
+git pull
+
+# 或 上传新代码（方式二）
+# 重复"上传代码"步骤
+
+# 重新构建并启动
+docker-compose up -d --build
+
+# 数据不会丢失（挂载卷）
+```
+
+---
+
+## 常用命令
+
+```bash
+# 查看日志
+docker logs -f piano-plan
+
+# 重启服务
+docker-compose restart
+
+# 停止服务
+docker-compose stop
+
+# 删除容器（数据不丢失）
+docker-compose down
+
+# 完全删除（包括镜像）
+docker-compose down --rmi local
+```
+
+---
+
+## 故障排查
+
+### 容器启动失败
+
+```bash
+# 查看日志
+docker logs piano-plan
+
+# 检查端口
+netstat -tlnp | grep 5000
+```
+
+### 数据库问题
+
+```bash
+# 进入容器检查
+docker exec -it piano-plan sh
+
+# 检查数据目录
+ls -la /app/data/
+```
+
+---
+
+## 版本信息
+
+| 日期 | 版本 | 说明 |
+|------|------|------|
+| 2026-04-18 | V1.2 | 初始部署版本，含用户/角色/班级管理 |
+
+---
+
+## 联系
+
+部署完成后访问: `http://47.106.65.108:5000`