Archived
chore: 基线快照 —— 纳入 git 版本控制（站点 v2.4.0 / Flask 单体）
在框架迁移与模块拆分前保存当前可运行状态： - 后端：main.py/auth_routes.py/auth_system.py/music_api.py/music_downloader.py/podcast_api.py/qr_login.py - 前端：templates/index.html + static/site_auth.js - 部署：Dockerfile/docker-compose.yml/entrypoint.sh/requirements.txt 敏感数据(data/、cookie.txt)与内部文档(交接文档/新会话引导)按 .gitignore 排除。
This commit is contained in:
snowy-yang committed
commit
d209af847a
21 files changed
+20816
No files matched your search
@@ -0,0 +1,190 @@
|
||||
# 云村小助手 · 部署文档（仅 Docker/Linux 轨道）
|
||||
|
||||
> **轨道定位（2026-09-25）**：本文档**只覆盖 Docker/Linux 一键部署**这一条轨道。
|
||||
> 正式部署轨道（Windows 工作站 + NSSM 服务 + PassNAT/Caddy HTTPS）以 `交接文档.md` 第 5/6 节为准——两份文档不要混用。
|
||||
> 涵盖：Docker 一键部署、站点配置、安全机制说明与常见问题。
|
||||
|
||||
---
|
||||
|
||||
## 一、环境要求
|
||||
|
||||
| 项目 | 要求 |
|
||||
| ---- | ---- |
|
||||
| 操作系统 | Linux（推荐 CentOS 7+ / Ubuntu 18+ / Debian 10+） |
|
||||
| Docker | 20.10+ |
|
||||
| Docker Compose | v2.24+（`docker compose` 命令；compose 文件用了 env_file.path/required 语法，v2.24 以下请删掉 docker-compose.yml 中该两行） |
|
||||
| 内存 | ≥ 1GB（含 ffmpeg 元数据写入建议 2GB） |
|
||||
| 磁盘 | ≥ 5GB（下载文件与数据库备份） |
|
||||
| 网络 | 服务器需能访问网易 API 与外网（IP 归属地检测、音频代理） |
|
||||
|
||||
---
|
||||
|
||||
## 二、文件说明
|
||||
|
||||
```
|
||||
Netease_url/
|
||||
├── main.py # Flask 主程序（路由、计费、音频代理防护）
|
||||
├── auth_system.py # 站点账号系统（SQLite：用户/卡密/公告/日志/封禁/顶号）
|
||||
├── auth_routes.py # 认证与管理后台路由
|
||||
├── music_api.py # 网易云音乐 API 封装
|
||||
├── music_downloader.py # 下载器（ffmpeg 元数据 / ZIP 打包）
|
||||
├── podcast_api.py # 播客解析 API
|
||||
├── qr_login.py # 网易云扫码登录
|
||||
├── templates/index.html # 前端页面（原生 HTML/CSS/JS）
|
||||
├── static/site_auth.js # 前端认证 / 个人中心 / 管理后台交互
|
||||
├── requirements.txt # Python 依赖（Python 3.12）
|
||||
├── Dockerfile # 镜像构建文件
|
||||
├── docker-compose.yml # 编排配置（端口 / 持久卷）
|
||||
├── entrypoint.sh # 容器启动脚本
|
||||
├── cookie.txt # 全局网易云账号 Cookie（部署后扫码生成，勿提交）
|
||||
├── user_cookie.txt # 游客个人 Cookie（浏览器端，勿提交）
|
||||
├── data/ # 站点数据库 site.db 与备份（运行时生成）
|
||||
├── downloads/ # 下载文件目录（运行时生成）
|
||||
├── 功能介绍.md # 功能清单
|
||||
└── 部署文档.md # 本文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、快速部署（Docker Compose）
|
||||
|
||||
### 1. 上传源码
|
||||
|
||||
将整个项目目录上传至服务器，例如 `/www/wwwroot/Netease_url`。
|
||||
|
||||
### 2. 配置环境变量
|
||||
|
||||
项目根目录创建 `.env` 文件（也可直接使用，默认即可运行）：
|
||||
|
||||
```ini
|
||||
TZ=Asia/Shanghai
|
||||
```
|
||||
|
||||
### 3. 构建并启动
|
||||
|
||||
```bash
|
||||
cd /www/wwwroot/Netease_url
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
首次构建约 3-5 分钟（已配置阿里云加速源）。启动后检查：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:5001/health
|
||||
# 返回 {"status":200,...} 即部署成功
|
||||
```
|
||||
|
||||
### 4. 访问
|
||||
|
||||
浏览器打开 `http://服务器IP:5001`（对外端口 5001，容器内 5000；勿改用 6000——浏览器会拦截 `ERR_UNSAFE_PORT`）。
|
||||
|
||||
---
|
||||
|
||||
## 四、初始配置（必读）
|
||||
|
||||
### 1. 管理员账号
|
||||
|
||||
新装实例的服务**首次启动时会在控制台随机打印初始管理员密码**（账号 `admin`，请翻阅启动日志获取）。
|
||||
登录后自动进入后台 → 请立即在「用户管理」中**重置密码**。
|
||||
**注意：管理员账号已升级两步验证登录（2026-09-24）**——输入正确的用户名+密码后，还需输入管理员绑定的邮箱并通过邮箱验证码验证，才能进入后台；请先在数据库或后台为管理员账号绑定可用邮箱。
|
||||
|
||||
### 2. 网易云全局账号
|
||||
|
||||
后台 →「全局 Cookie」→ 生成二维码 → 用网易云 App 扫码登录。
|
||||
全局账号负责默认解析与下载，黑胶/SVIP 账号可解析更高音质。
|
||||
|
||||
### 3. SMTP 邮箱（开启用户注册必须配置）
|
||||
|
||||
后台 →「邮箱注册管理」→ 填写：
|
||||
|
||||
| 项 | 说明（以 QQ 邮箱为例） |
|
||||
| ---- | ---- |
|
||||
| SMTP 服务器 | `smtp.qq.com` |
|
||||
| 端口 | `587` |
|
||||
| 发件邮箱 | 你的 QQ 邮箱 |
|
||||
| 邮箱密码/授权码 | QQ 邮箱「设置 → 账户 → 开启 SMTP」获取的**授权码**（非 QQ 密码） |
|
||||
|
||||
保存后用「发送测试邮件」验证。
|
||||
|
||||
### 4. 公告与卡密
|
||||
|
||||
- 后台 →「公告设置」：编辑公告内容与弹出策略（每次登录弹出 / 仅一次 / 不弹出）。
|
||||
- 后台 →「次数卡密」：生成次数卡（张数、类型或自定义次数、前缀、备注、有效天数），用户在个人中心兑换充值。
|
||||
|
||||
---
|
||||
|
||||
## 五、站点机制说明
|
||||
|
||||
| 机制 | 说明 |
|
||||
| ---- | ---- |
|
||||
| 强制登录 | 所有解析 / 下载接口需登录；未登录弹窗引导注册/登录 |
|
||||
| 按次计费 | 解析 / 试听 / 浏览免费；**下载扣次数**：单曲 1 次，打包按歌曲数（100 首歌单 = 100 次）；失败不扣费；管理员不限 |
|
||||
| 注册赠送 | 注册成功自动赠送 3 次下载次数 |
|
||||
| 批量预检 | 打包下载前检查次数，不足可选择「仅下载前 N 首（集）」或取消 |
|
||||
| 顶号机制 | 同一账号新设备登录后旧会话立即失效 |
|
||||
| 防倒卖封禁 | 登录记录 IP 归属省份，24h 内 ≥3 个不同省份自动封禁；管理员可手动封禁 / 解封 |
|
||||
| 音频防护 | 音频直链经服务器签名代理（HMAC + 36 分钟时效），真实 CDN 链接不暴露 |
|
||||
| 日志审计 | 成功 / 失败日志 10 条每页分页，可清除；记录封禁、顶号、扣费等关键事件（不含普通登录注册） |
|
||||
|
||||
---
|
||||
|
||||
## 六、数据持久化
|
||||
|
||||
`docker-compose.yml` 已配置挂载，**重建容器数据不丢失**：
|
||||
|
||||
| 宿主机路径 | 容器路径 | 内容 |
|
||||
| ---- | ---- | ---- |
|
||||
| `./cookie.txt` | `/app/cookie.txt` | 全局网易云 Cookie |
|
||||
| `./user_cookie.txt` | `/app/user_cookie.txt` | 游客个人 Cookie（兼容） |
|
||||
| `./downloads/` | `/app/downloads` | 下载文件 |
|
||||
| `./data/` | `/app/data` | 站点数据库 `site.db`（用户/卡密/日志/公告）与自动备份 |
|
||||
|
||||
> 建议定期在 后台 →「数据库管理」下载备份；更换服务器时将整个目录拷贝即可完整迁移。
|
||||
|
||||
---
|
||||
|
||||
## 七、常用运维命令
|
||||
|
||||
```bash
|
||||
# 启动 / 重建（代码更新后）
|
||||
docker compose up -d --build
|
||||
|
||||
# 查看运行日志
|
||||
docker logs -f netease_url-netease-url-1
|
||||
|
||||
# 重启
|
||||
docker compose restart
|
||||
|
||||
# 停止
|
||||
docker compose down # 数据保留（挂载卷）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、常见问题
|
||||
|
||||
**Q1：端口被占用（5001 already allocated）**
|
||||
`docker ps` 查看占用容器并 `docker rm -f 容器名`，或修改 `docker-compose.yml` 端口映射。
|
||||
|
||||
**Q2：页面样式/功能异常**
|
||||
浏览器 **Ctrl+F5** 强制刷新缓存（前端资源带版本号，一般自动生效）。
|
||||
|
||||
**Q3：收不到邮箱验证码**
|
||||
检查 SMTP 配置与授权码；确认服务器出站 587 端口可用；查看失败日志定位报错。
|
||||
|
||||
**Q4：用户反馈「已被封禁」**
|
||||
后台 →「用户管理」查看该用户最近登录省份与封禁原因，确认无误后可解封。
|
||||
|
||||
**Q5：忘记管理员密码**
|
||||
```bash
|
||||
docker exec -it netease_url-netease-url-1 python3 -c "
|
||||
import auth_system as a
|
||||
# 若实例管理员已由 admin 更名（如 qfbsh），请把 'admin' 替换为实际用户名
|
||||
a.set_user_password(a.get_user_by_name('qfbsh')['id'], '新密码至少8位')
|
||||
print('已重置')"
|
||||
```
|
||||
|
||||
**Q6：数据库损坏 / 恢复**
|
||||
后台 →「数据库管理」→ 上传历史备份文件即可覆盖恢复。
|
||||
|
||||
---
|
||||
Reference in new issue
Block a user