NeteaseUrl/部署文档.md

云村小助手 · 部署文档（仅 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 归属地检测、音频代理）

---

二、文件说明

NeteaseUrl/
├── web/                    # FastAPI 应用（唯一服务端）
│   ├── main.py             # uvicorn 入口（python web/main.py）
│   ├── app.py              # create_app 工厂（挂路由 / 静态资源 / 中间件）
│   ├── deps.py             # 会话解析、当前用户、登录/管理员依赖
│   ├── billing.py          # 计费依赖（预扣+开账同事务、只退 open 行）
│   ├── tasks_registry.py   # 任务登记/启动（容量闸、账本承接）
│   ├── middleware.py       # 安全头 + 音频直链签名保护
│   ├── ratelimit.py        # 按 IP 滑动窗限流（与 core.state 共享桶）
│   ├── auth_state.py       # 登录失败锁定 / 管理员 2FA 票据 / 发码限流
│   └── routers/            # 各领域路由（music/podcast/download/auth/admin…）
├── core/                   # 框架无关核心层
│   ├── config.py           # 常量与配置
│   ├── state.py            # 进程内运行时状态（任务表/限流桶/缓存）
│   ├── db.py / repo.py     # 异步 SQLite（WAL：读并发、写串行）
│   ├── http_client.py      # aiohttp 连接池客户端
│   ├── aiohttp_compat.py   # requests 同形异步垫片
│   ├── async_bridge.py     # 同步↔异步桥（遗留同步调用点）
│   ├── session.py          # itsdangerous 兼容会话编解码
│   ├── security.py         # 音频 HMAC 签名
│   ├── net.py / media.py / utils.py / serializers… # 纯工具
├── services/runtime.py     # 服务层（MusicAPIService、下载/打包 worker、任务监控）
├── auth_system.py          # 站点账号系统（SQLite：用户/卡密/公告/日志/封禁/顶号）
├── 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     # 前端认证 / 个人中心 / 管理后台交互
├── pyproject.toml          # 依赖与工具配置（uv 管理）
├── uv.lock                 # 精确锁定依赖版本
├── tests/                  # 测试（含 golden 契约回归）
├── Dockerfile              # 镜像构建文件（uv sync）
├── 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 文件（也可直接使用，默认即可运行）：

TZ=Asia/Shanghai

3. 构建并启动

cd /www/wwwroot/Netease_url
docker compose up -d --build

首次构建约 3-5 分钟（已配置阿里云加速源）。启动后检查：

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（用户/卡密/日志/公告）与自动备份

建议定期在 后台 →「数据库管理」下载备份；更换服务器时将整个目录拷贝即可完整迁移。

---

七、常用运维命令

# 启动 / 重建（代码更新后）
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：忘记管理员密码

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：数据库损坏 / 恢复 后台 →「数据库管理」→ 上传历史备份文件即可覆盖恢复。

---