Skip to content
minecraftmc22Public

About

WinUI3 / Fluent Design 风格的二次元个人网盘,Python 3.14 + FastAPI 后端,零构建原生 ES Module 前端。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

CloudNETP

CloudNETP

自托管的二次元个人网盘 · WinUI 3 / Fluent Design 风格 · 文件只放在你自己的机器上

Python FastAPI SQLAlchemy i18n License 文档 Docker Hub Deploy Wiki Docker Image

Python 3.14 + FastAPI 后端,零构建原生 ES Module 前端;分片秒传、在线预览、分享链接、WebDAV、管理后台与看板娘 AI 助手一应俱全,多用户各占独立空间与配额。

界面预览

文件管理 图片预览
文件管理 · 网格 / 列表双视图,多选、拖拽上传、右键菜单 在线预览 · 图片缩放拖动,音视频与文档就地打开
Markdown 预览 设置
文档预览 · Markdown / Word / Excel / PPT / ODF / PDF 直接在浏览器里看 外观设置 · 亮暗主题、主题色、预设壁纸、各模块不透明度
管理后台 公开分享页
管理后台 · 用户与配额、审计日志、数据库状态、孤儿文件清理 分享链接 · 独立公开页,有效期 / 提取码 / 次数上限

登录页
登录页 · 花瓣粒子背景,右上角直接切换中英文

手机端
手机端 · 三列网格 + 底部图标导航

特性

  • 文件管理:目录树、网格 / 列表双视图、多选(Ctrl / Shift)、右键菜单、面包屑、搜索、重命名、移动、回收站
  • 上传:拖拽上传(文件夹保留目录结构、同名目录自动合并、空目录也建)、分片断点续传、SHA-256 秒传去重、实时进度与速度;队列是全局的,切到别的页面也会继续在后台传,每个任务可暂停 / 继续(从已传分片接着走),也能一键收起(按设备记忆),失败的条目点一下刷新图标就重传
  • 下载:支持 Range(断点续传 / 视频拖动进度条)
  • 在线预览:图片(缩放 / 拖动 / 快捷键)、文本(多编码探测)、音视频(ArtPlayer + 弹幕 / 多字幕 / 章节 / 进度缩略图 / 氛围光,同名伴生文件自动挂载)、音频全屏歌词(读取 ID3 内嵌元数据与封面,逐词滚动歌词 + 控制栏;在线歌词支持网易云与 MC22 歌词库两个来源,网易云可在后台扫码登录、Cookie 只留服务端、可在搜索时按分类切换——网易云免密钥即得逐行歌词,配 Cookie 后升级为逐字歌词与翻译,两个来源可同时启用,歌词经服务端代理,Cookie 与密钥不出服务端)、PDF
  • 意见反馈:入口在「关于」页,站内提交建议 / 问题,管理员在后台标记处理,反馈只有管理员可见
  • 版本检查与更新:关于页可手动检查;管理员可开启自动检查提示,或在后台手动/自动更新(git fast-forward + 重启,要求 main 分支、工作区干净)
  • 分享链接(列表分页,失效记录可重新分享或删除):有效期 / 提取码(scrypt 哈希存储)/ 下载次数上限、独立公开页;合集链接支持勾选转存,转存时可以在弹窗里浏览自己的文件夹、选好目标目录再存;双击文件就地预览。访客未登录时分享页右上角会显示「登录 / 注册」,登录后自动跳回原来那条分享链接(提取码一并带上)
  • 回收站:保留期自动清理、可整体关闭(需抄写服务端签发的一次性验证码)
  • 快传:三种「不等你进网盘也能拿到文件」的方式——①扫码直传:电脑生成二维码 / 一次性链接,手机扫码并登录后就能选照片和文件,直接落进指定目录(省掉在手机上找目录,但上传仍要本人登录,避免链接外泄被人灌文件);②发给用户:选中文件或文件夹填对方用户名,直接复制进对方根目录(同内容只占一份磁盘)并带附言与未读提示;③取件码:生成 6 位码,任何人打开 /pickup 输码即可下载;可以直接拖入 / 选择本机文件(多选)生成,快传文件不占网盘配额、也不出现在「我的文件」里,同时也能给已有的文件生成;每个文件可单独设有效期与下载次数,登录后还能输入别人的码取件、一键转存到自己的目录;管理员可设有效期 / 次数上限与过期后文件保留天数,并在后台一键清理过期文件(只删快传自己存的文件)。首次使用要先同意《快传使用规范》(禁止上传违法违规内容,违者封号并追究法律责任);上传会比对已被举报确认的文件哈希并直接拒绝,取件页的每个文件都能匿名举报,审核通过即全网盘禁用该内容
  • 站内公告:管理员在「系统设置 → 站点 → 公告」里写一条,登录页卡片里与主界面标题栏下方都会显示;超过三行折叠成「展开」,关掉后按内容记在本机,改了内容会再出现一次
  • 管理后台:运行概览、用户管理(配额 / 封禁(原因 + 时长,到期自动解封) / 重置密码 / 角色 / 级联删除)、封禁申诉审核、系统设置、审计日志(80+ 类动作,不再一律显示「其它操作」)、孤儿文件清理。被ban的用户在线时会收到「你已被管理员封禁」弹窗(原因 / 封禁时间 / 解封时间 / 去申诉),不在线则下次登录直接进申诉页。成员角色分三级:第一位注册的账号是超级管理员,可以在后台把任何人设为管理员 / 超管或收回;普通管理员只能查看成员、调配额与密码、封禁,不能增减管理员、也动不了超管(超管的密码重置 / 封禁 / 删除同样被挡住)。想在数据库里开多个超管,把 users.is_super 设为 1 即可(启动时会自动补齐 role=1)
  • WebDAV:/dav 直接挂载(Windows 资源管理器 / Finder / RaiDrive),Digest + Basic 认证、PROPFIND / LOCK / MOVE / COPY 全支持,写入同样受配额与审计约束;.env 的 WEBDAV_ENABLED 是总开关(管理后台「站点」里可改,后台优先),每个用户也能在自己的「设置 → WebDAV」里单独关掉
  • 界面:Mica 亚克力卡片、可折叠 NavigationView、亮 / 暗 / 跟随系统、主题色(预设 / 取色器 / 从背景图取主色)、4 种预设壁纸或上传自己的图片当背景、侧栏 / 标题栏 / 内容面板 / 卡片 / 弹窗各自可调背景不透明度(卡片管设置卡、关于卡、快传卡、统计卡与文件磁贴)、花瓣粒子、看板娘「CDP娘」(可拖动、鼠标停在她身上滚轮就能缩放、悬停出「锁定 / 对话 / 关闭」,设置里可一键重置位置、也能关掉滚轮缩放,均可关闭);设置页按 WinUI 3 的分组卡片排版,手机端底部栏只留图标
  • CDP娘 AI 对话:点「对话」开右下角浮层,SSE 流式输出、思考过程单独折叠、工具调用(翻目录 / 搜文件 / 查容量);「数据操作权限」里的「查看文件内容」勾选后才能读文本正文、看图片(png / jpg / webp / gif,需同时开「图片输入」,默认关闭)、读音视频的元数据标签(mp3 / flac / m4a / mp4 / mkv / avi 等,只报标签不读媒体内容),再勾写/移动权限才能新建文件夹、写改文本文件、改名、复制、移动——未授权的工具模型手里根本没有,服务端执行前还会再校验一次,每次读正文/看图/写操作都会在对话里标出来并记审计日志。另有「快传取件码」权限:开了之后可以让 CDP娘 按确认给文件生成取件码,或用取件码取件(转存到指定目录 / 给出下载链接);所有工具调用集中在回答下方的「使用工具 N」里,点一下才展开。底栏右侧实时显示这一问的输入 / 输出 token(流式时按已收字符估算、带 ≈,结束后换成服务商给的准数,悬停看本次累计),可在设置里关掉;走管理员默认接口时不显示也不索要用量。接口在「设置 → 看板娘 → 对话设置」里自填(OpenAI 兼容或 Anthropic,密钥 Fernet 加密落库、只回掩码),填完自动探测模型列表,支持图片输入、思考模式、自定义协议与输入/输出上限;系统提示词由管理员维护。对话失败时那条提问左边会出现「重新发送」(连同半截回答一起重来),每条气泡下方都有「编辑 / 删除」:编辑把内容放回输入框、改完发送即替换原来那一轮,删除按两下确认,删掉回答后再次发送会自动合并相邻同角色消息(部分接口不接受连续同角色)。.env 里的 AI_ENABLED=false 可整块关掉(对话入口隐藏、接口 403);AI_DEFAULT_* 可提供一套默认接口——用户不用自己填就能聊,但地址与密钥只对管理员可见(管理后台「看板娘 AI 默认接口」可查看/覆盖,优先级高于 .env),用户自己填全了就用自己的
  • 账号:多用户注册、独立空间与配额、scrypt 密码哈希、HMAC 会话 Cookie、登录限流;注册页的密码框带「显示密码」按钮,确认密码边输边比对;「设置 → 账号 → 危险区域」可注销账号——先列清后果,再用「密码 + 绑定邮箱」(没绑邮箱就只用密码)验证一次,确认后立即删除账号、文件、分享、快传、看板娘对话与记忆,清掉登录态并记审计;最后一名管理员 / 最后一个超管不能注销,避免把站点删成没人管
  • 数据:SQLAlchemy 2.x + MySQL 8 / SQLite;主库与次库可以分别选类型,次库还能不设;主库连不上时自动降级次库并自动回迁(见「数据库(主库 / 次库)」)

全站不使用原生 alert / confirm,所有提示均为自绘 Dialog / Toast / 菜单组件。

快速开始

两种装法任选其一:Docker(服务器 / NAS 推荐,机器上不用装 Python)或本地 Python。 两者配置方式完全一样 —— 都只读根目录的 .env。

方式一:Docker 部署(推荐)

镜像里已经带好 Python 与全部依赖,数据只落在宿主机的 ./data,升级就是重建镜像。

1. 准备配置

cp .env.example .env
python -c "import secrets;print(secrets.token_hex(32))"   # 生成一串填进 SECRET_KEY

.env 里至少确认这三项:

变量 说明
SECRET_KEY 必填一串长随机值;留空则每次重启所有登录会话失效
PORT 对外端口,compose 的端口映射跟着它走(.env.example 里是 8000;删掉这行就用镜像默认的 8123)
SITE_URL 有域名 / 反向代理时填 https://pan.example.com,分享链接与 WebDAV 地址会用它

2. 起服务

docker compose up -d --build      # 首次会构建镜像
docker compose logs -f            # 看启动日志(含实际监听地址与 WebDAV 地址)

国内默认走阿里云 PyPI 镜像,海外构建可以:

PIP_INDEX_URL=https://pypi.org/simple docker compose build

3. 打开

http://<主机IP>:<PORT>(本机就是 http://localhost:8000)。第一个注册的账号自动成为超级管理员。 容器自带 healthcheck,docker compose ps 里显示 healthy 就表示接口已经能应答。

4. 数据在哪

容器内路径 宿主机 内容
/data/dev.db ./data/dev.db SQLite 数据库(接了 MySQL 后这里只剩容灾副本)
/data/storage ./data/storage 上传的原始文件、缩略图、头像、背景图

备份 = 复制宿主机上的 ./data 整个目录。镜像里已经把 /app/dev.db 与 /app/storage 软链接到 /data,所以 .env 里的 sqlite:///./dev.db、留空的 STORAGE_DIR 不用为容器改。

5. 常见问题

  • 启动后写文件失败 / 报权限错误:宿主机 ./data 属主是 root,而容器里跑的是 uid 10001。 执行一次 sudo chown -R 10001:10001 data,或者在 docker-compose.yml 里打开 user: "1000:1000" 注释并改成 id -u / id -g 的结果。
  • 从本机 .env 直接拷过来时:把 SSL_CERTFILE / SSL_KEYFILE 留空(容器里没有那些证书路径, 填了会启动失败并提示文件不存在),UPDATE_PROXY 也别指向 127.0.0.1(那是容器自己)。
  • 想用 MySQL:docker compose -f docker-compose.mysql.yml up -d --build。 自带 MySQL 8.4(数据在 mysql-data 卷里),记得改 .env 或 compose 里的 MYSQL_PASSWORD。 接外部 MySQL 则直接改 .env 的 DATABASE_URL(容器里访问宿主机用 host.docker.internal)。
  • 反向代理 / HTTPS:容器只提供 HTTP,TLS 交给 Nginx / Caddy,记得转发 X-Forwarded-Proto (TRUST_PROXY 默认开启),并把 .env 的 SITE_URL 与 COOKIE_SECURE=true 配上。
  • 自动更新不可用:镜像里没有 .git,关于页的「更新」会失败;自己构建的用 docker compose build --pull && docker compose up -d,用发布镜像的用 docker compose -f docker-compose.hub.yml pull && docker compose -f docker-compose.hub.yml up -d。
  • 想看/改 Live2D 模型:docker-compose.yml 里有把 ./live2d 挂进容器的注释,打开即可。
  • 调整上传体积上限 / 配额:改 .env 里的 MAX_FILE_SIZE_MB / DEFAULT_QUOTA_GB 后 docker compose up -d 重启即可。

6. 或者直接用发布好的镜像

不想在机器上构建也行:仓库每次打 tag 都会由 GitHub Actions 构建多架构镜像(amd64 + arm64) 推到 Docker Hub,docker-compose.hub.yml 就是给这种用法准备的,.env、./data、端口跟上面一模一样:

docker compose -f docker-compose.hub.yml up -d                    # 跟随 latest
IMAGE_TAG=0.3.67 docker compose -f docker-compose.hub.yml up -d   # 固定版本
镜像 tag 含义
latest 最近一次正式发布的 tag(预发布 tag 不会顶掉它)
0.3.67 与 app/config.py 的 VERSION 一致;打 v0.3.67 时镜像名里不带 v
0.3.67-beta 手动运行工作流时自定义的 tag

维护者发版:git tag v0.3.67 && git push origin v0.3.67,然后到 Actions 的 「Build and Push Docker Image」看进度。仓库要在 Settings → Secrets 里配好 DOCKERHUB_USERNAME 与 DOCKERHUB_TOKEN(Docker Hub 的 Read & Write Access Token); 没配时工作流只构建镜像、跳过推送。

方式二:本地安装(Python)

需要 Python 3.10+(推荐 3.13 / 3.14)。仓库自带启动脚本,首次运行会自动建 .venv、 装依赖、从 .env.example 生成 .env 并补一个随机 SECRET_KEY;之后每次启动直接跑脚本即可。

Windows(PowerShell,或直接双击 start.bat):

.\start.ps1          # 生产启动:读 .env,不热重载
.\start.ps1 -Dev     # 开发模式:监视 app/ 与 static/,改代码自动重启

若提示「在此系统上禁止运行脚本」,改用 powershell -ExecutionPolicy Bypass -File .\start.ps1(start.bat 已经这么做了)。

Linux / Ubuntu:

chmod +x start.sh    # 只需一次
./start.sh           # 生产启动
./start.sh --dev     # 开发模式

Ubuntu 缺 venv 时先装:sudo apt install -y python3 python3-venv python3-pip。 脚本默认用阿里云 PyPI 镜像,要换源:

# Linux
PIP_INDEX_URL=https://pypi.org/simple ./start.sh
# Windows PowerShell
$env:PIP_INDEX_URL = "https://pypi.org/simple"; .\start.ps1

手动启动(不用脚本时,注意用虚拟环境里的解释器;直接 python run.py 是系统 Python, 没装依赖会报 ModuleNotFoundError):

python3 -m venv .venv

# Linux / Ubuntu
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/bootstrap.py   # 生成 .env + SECRET_KEY
.venv/bin/python run.py                 # 生产
.venv/bin/python main.py                # 开发(热重载)

# Windows(PowerShell / cmd)
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe scripts\bootstrap.py
.venv\Scripts\python.exe run.py
.venv\Scripts\python.exe main.py

⚠️ uvicorn app.main:app --reload 这类直接调用 uvicorn 的启动方式不会读 .env, 会退回 uvicorn 自己的默认值 127.0.0.1:8000。要自定义地址请补上 --host 0.0.0.0 --port 8000,或者干脆用上面的 run.py / main.py。 另外环境变量优先级高于 .env,IDE 运行配置里写了 PORT 会盖掉 .env。

⚠️ 两处容易踩的坑(0.3.0 起启动日志会直接打印正确地址):

  • 0.0.0.0 只能用于监听,不能填进浏览器。它表示「本机所有网卡」,不是一个可路由的目的地址, Chrome 124+ 会直接拦掉。本机请开 http://localhost:8000,别的设备用 http://<本机局域网IP>:8000。
  • uvicorn main:app --reload 会监视整个项目根目录(日志第一行的 Will watch for changes in these directories), 上传文件写 storage/ 也会触发重启。开发请用 main.py 入口(start.sh --dev / start.ps1 -Dev 就是它), 它只监视 app/ 与 static/。

首次启动默认用 SQLite(项目根目录的 dev.db),要接 MySQL 改 .env 里的 DATABASE_URL 再重启即可。启动脚本会打印实际监听地址与 WebDAV 地址。想改端口或绑域名改 .env 即可:

变量 说明
HOST / PORT 监听地址与端口(0.0.0.0 允许局域网/公网访问)
SITE_URL 对外站点地址(绑域名 / 反向代理时填),分享链接与 WebDAV 地址会用它
SSL_CERTFILE / SSL_KEYFILE 由 uvicorn 直接提供 HTTPS 时填证书路径;交给 Nginx/Caddy 就留空
RELOAD / TRUST_PROXY 开发热重载;反向代理转发时信任 X-Forwarded 头
UPDATE_REPO / UPDATE_TOKEN 检查更新用的 GitHub 仓库;私有仓库需只读 PAT(Contents: Read)
UPDATE_PROXY 直连 GitHub 失败时的本地代理,如 http://127.0.0.1:7897
CLOUDNETP_RESTART_CMD 自动更新后的重启命令(systemd / nssm 等);留空用内置 restart_helper.py

自动/手动更新只对 git 检出 生效:要求 main 分支、工作区无未提交改动、git fetch/pull 凭据可用;更新只做 fast-forward,不会覆盖本地提交。Docker / 压缩包部署请在宿主机重新拉取镜像或覆盖文件。

首个注册的账号自动成为超级管理员,可以在后台把其他人设为管理员或超管。

目录结构

start.sh / start.ps1 / start.bat   一键启动(Linux / Windows)
Dockerfile           镜像构建(python:3.12-slim,数据统一放 /data)
docker-compose.yml   compose 部署:SQLite + 宿主机 ./data
docker-compose.mysql.yml  compose 部署:应用 + MySQL 8.4
docker-compose.hub.yml    compose 部署:直接用 Docker Hub 上发布好的镜像
run.py               生产入口:读 .env,热重载看 RELOAD
main.py              开发入口:读 .env + 强制热重载
app/
  config.py          .env 解析与配置
  db.py              引擎 / 会话 / 建表
  models.py          数据表 ORM 模型(用户 / 节点 / 分享 / 快传 …)
  security.py        scrypt 哈希、HMAC 令牌、限流
  storage.py         blob 内容寻址存储、Range 响应
  node_service.py    目录树与回收站逻辑
  upload_service.py  分片上传、合并、秒传
  share_service.py   分享链接与访问控制
  quick_service.py   快传:扫码直传会话、站内投递、取件码
  admin_service.py   管理后台统计与维护
  dav_service.py     WebDAV 路径解析、multistatus 拼装、内存锁、子树复制
  ai_service.py      看板娘 AI:配置、模型探测、SSE 流式、工具调用、系统提示词
  routers/           auth / nodes / uploads / shares / quick / admin / dav / ai / live2d
static/
  css/               theme / layout / components / views / files / viewer / admin / share / quick / legal
  js/                api / store / theme / uploader / sha256 / i18n / views / ui
  quick.html         快传公开页(/pickup 取件、/drop/<token> 手机上传)
  vendor/qrcode.js   内置二维码生成(MIT,不依赖外网)
  terms.html         用户协议(/terms)
  privacy.html       隐私政策(/privacy)
scripts/
  bootstrap.py       首次启动:生成 .env 与随机 SECRET_KEY
  make_readme_shots.py  生成 docs/screenshots 里的界面截图(临时库 + 演示数据)
docs/
  logo.png           图标(与站点 PWA 图标同源)
  screenshots/       README 界面截图
Wiki/                使用文档(VuePress + vuepress-theme-hope,含操作截图)
.github/workflows/
  deploy-wiki.yml    推送 Wiki/ 时自动构建并发布到 GitHub Pages
  docker-publish.yml 打 tag 时构建镜像(amd64 + arm64)并推送到 Docker Hub
sql/schema.sql       MySQL 建表参考

依赖说明

只依赖 8 个包(fastapi、uvicorn、sqlalchemy、pymysql、cryptography、pillow、mutagen、qrcode)。 上传走裸流与分片协议,未使用 python-multipart;密码哈希用标准库 hashlib.scrypt, 会话令牌自行 HMAC 签名,因此不引入 passlib / itsdangerous / PyJWT;前端不打包、不引 CDN, 第三方脚本都放在 static/vendor/ 里随仓库分发。

环境变量

变量 说明
DATABASE_URL mysql+pymysql://user:pass@host:3306/db?charset=utf8mb4 或 sqlite:///./dev.db
SECRET_KEY 会话签名密钥。start.sh / start.ps1 首次运行会自动生成并写进 .env;留空则用临时密钥(重启即失效)
STORAGE_DIR 文件落盘目录,默认 ./storage
DEFAULT_QUOTA_GB 新用户默认配额
MAX_FILE_SIZE_MB 单文件大小上限
DB_CONNECT_TIMEOUT / DB_TIMEOUT 远程数据库连接 / 读写超时(秒)
DB_AUTO_CREATE 启动时是否自动建表
DB_PRIMARY 主库类型:mysql / sqlite;留空按 DATABASE_URL 自动判断(后台选过角色则以 storage/db/roles.json 为准)
DB_SECONDARY 次库类型:mysql / sqlite / none(不设置);留空跟着 DB_FALLBACK_ENABLED 走
DB_FALLBACK_ENABLED 老开关,等价于「次库 = sqlite / none」:主库连不上时是否降级本地 SQLite(默认开;多实例部署请关)
DB_PROBE_INTERVAL 主库探活间隔秒数(0 = 只在启动时选库,运行期不切换)
DB_MIRROR_INTERVAL 主库 → SQLite 镜像间隔秒数(0 = 不做周期镜像)
LYRICS_PROVIDERS 启用的歌词来源,逗号分隔(netease,lyriclib),顺序即优先级;all = 全部;留空退回 LYRICS_PROVIDER。管理后台「歌词来源」里的设置优先于这里
LYRICS_PROVIDER 单值默认来源(老写法,仍然兼容)
NETEASE_COOKIE 网易云网页版 Cookie(含 MUSIC_U=...)。配了才有逐字歌词与翻译,不配也能用(逐行)
LYRICS_API_BASE / LYRICS_API_KEY / LYRICS_API_COOKIE MC22 歌词库的地址 / 开发者密钥 / 站点 Cookie

歌词来源(网易云 / 歌词库)

音频全屏播放器里的在线歌词支持两个来源,可以同时启用:

来源 id 凭据 说明
网易云 netease NETEASE_COOKIE(可选) 免密钥直接搜;配 Cookie 后拿逐字歌词(yrc)与翻译,不配就是逐行(lrc)
MC22 歌词库 lyriclib LYRICS_API_KEY(必需)+ LYRICS_API_COOKIE(可选) 自建站点的开发者 API

管理后台 → 系统设置 → 歌词来源 可以直接改(存 system_settings,保存即生效,不用重启):

  • 两个来源的开关、歌词库地址、API 密钥、站点 Cookie 都在这一张卡片里;
  • 密钥与 Cookie 用 SECRET_KEY 派生的 Fernet 加密保存,接口只回掩码,浏览器拿不到原文;
  • 「测试连接」用当前填写的值试搜一首,测试本身不保存;
  • 优先级:后台保存的 > .env。卡片上每个字段都会标出当前用的是后台的、.env 的还是没配; 留空表示继续跟随 .env,清空用对应的「清除」勾选。
LYRICS_PROVIDERS=netease,lyriclib   # 顺序即优先级,也可以是 all
NETEASE_COOKIE=MUSIC_U=xxxxx
LYRICS_API_BASE=https://minecraftmc22.top/lyric/api/v1
LYRICS_API_KEY=xxxxx
LYRICS_API_COOKIE=session=xxxxx

LYRICS_PROVIDERS 与 LYRICS_PROVIDER 都不写时:配了歌词库密钥就两个都启用,否则只有网易云。

行为:

  • 搜索指定:歌词设置 → 搜索指定,搜索框上方出现来源分类(网易云 / 歌词库),点哪个就搜哪个; 只启用一个来源时不显示分类,直接搜那一个。选过的分类记在浏览器本地,下次打开还是它。
  • 自动匹配:按启用顺序(后台保存的或 LYRICS_PROVIDERS)依次尝试,先用先得;某个来源挂了会跳过 并继续试下一个,全部失败才报错。
  • 每首歌的来源会存下来:audio_prefs.provider 记录点选时用的是哪个来源(两个来源的歌曲 id 不互通)。 后来把某个来源从配置里去掉,老歌单里指向它的歌仍然能取到歌词。
  • 搜索/取词缓存都按来源分开((provider, song_id)),同一个 id 在两个来源里不会被当成同一首歌。
  • 凭据只读服务端:前端只调 /api/lyrics,Cookie 与密钥不会下发到浏览器。

接口:GET /api/lyrics/providers(可用来源与默认项)、GET /api/lyrics/search?q=&provider=、 GET /api/lyrics?songId=&provider=。

网易云:后台上扫码登录(不用手抄 Cookie)

管理后台 → 系统设置 → 网易云歌词 → 扫码登录,用网易云音乐 App 扫一下并确认,服务端会自己把 MUSIC_U / __csrf 取回来,加密存进 system_settings。之后取歌词直接用它,无需重启。

  • Cookie 不进浏览器:所有接口(状态/二维码/轮询)只回「是否已连接 + 昵称/头像/更新时间」, 任何响应都不含 Cookie 原文或名字;前端也拿不到,歌词请求全部由后端代发。
  • 优先级:后台上登录的 > .env 的 NETEASE_COOKIE。两者都有时用后台的;点「退出登录」只清后台那份, 会自动回退到 .env(卡片上会写明当前用的是哪一个)。
  • 登录态:system_settings.netease_cookie(Fernet 加密,密钥由 SECRET_KEY 派生)、 netease_cookie_at、netease_profile。SECRET_KEY 变了就要重新扫码。
  • 二维码:服务端用 qrcode 画成 SVG,有效期 3 分钟;过期/失效会提示重新获取。
  • 登录与退出都记审计(admin_netease_login / admin_netease_logout)。

数据库(主库 / 次库)

主库与次库可以分别选 MySQL 或 SQLite,次库还可以不设置:

  • 主库:平时真正在读写的那一个(DATABASE_URL 指向的库,或后台选的类型)。
  • 次库:主库连不上时自动接管的备胎;主库正常时定期把数据复制过来。
  • 次库不设置:只跑主库,没有容灾、也没有自动回切。

选择入口是管理后台 → 系统设置 → 数据库(两个下拉 + 「保存并切换」),保存后记在 storage/db/roles.json,重启仍然有效,优先级高于 .env 的 DB_PRIMARY / DB_SECONDARY。

阶段 行为
正常 每 DB_MIRROR_INTERVAL 秒把主库全表镜像进次库(审计日志只留最近 5000 条)
主库断连 看门狗(DB_PROBE_INTERVAL)探测失败 → 新请求全部改走次库,写 __failover_dirty 标记;文件本体在磁盘,不受影响
主库恢复 先把次库期间的变更回迁主库(按主键覆盖,可信副本才覆盖),成功后切回主库并立即重新镜像
降级期间重启 启动时发现 __failover_dirty 就先回迁再镜像,避免把降级期间的写入覆盖掉

几条边界:

  • 按单实例部署设计。多实例同时写主库时,回迁的「以次库为准」会打架,请把次库设为「不使用」。
  • 次库若是从未镜像成功过的新库(__failover_mirror_at 不存在),回迁只补缺失行、绝不覆盖主库 —— 宁可少迁,不能拿空库盖掉线上数据。
  • 主库和次库不能都是 MySQL(同一个库没法当自己的备份,后台会直接当作「不使用」);两个都选 SQLite 是可以的, 用的是两个不同文件(主库沿用 DATABASE_URL 指向的 dev.db,次库是 storage/db/fallback.db)。
  • 切换瞬间正在飞行的请求可能失败一次(旧连接已断),重试即可;新请求已走新库。
  • 内部标记键都以 __ 开头,只存在于次库,不会被同步进主库。
  • 镜像与回迁都按表逐行 upsert、单表一个事务;中途失败下一轮重试,不会写坏数据。

在后台管理(不用重启)

管理后台 → 系统设置 → 数据库 卡片会显示当前服务库、主库连接串(密码脱敏)、探活延迟、 次库的路径/体积/可信状态,以及看门狗的探测与镜像间隔。四个动作:

按钮 作用
保存并切换 按选中的主库 / 次库生效。换主库时先探活,通了把当前库的数据整体复制过去(旧库原样保留),连不上就报错并保持现状
刷新配置 重读 .env 里的 DATABASE_URL 与容灾参数,就地更新配置、重建连接池并重新探活;连接串变了会一起生效
重新连接 MySQL 丢弃旧连接池重新握手;若当前跑在 SQLite,先回迁本地数据,回迁成功才切回,连不上就报错并保持现状
重新连接 SQLite 先镜像一份最新副本,再切到本地库服务;切过来后暂停自动回切(否则 30 秒后看门狗就改回去了),点「重新连接 MySQL」或重启进程才恢复

刷新、换库与手动切换都会写入审计日志(admin_db_refresh / admin_db_roles / admin_db_reconnect)。刷新配置只覆盖 .env 里读进来的值:运维用 systemd / 命令行显式 export 的同名变量优先级更高,不会被文件覆盖。

多语言(i18n)

界面支持 简体中文 / English 两套文案,切换入口在「设置 → 外观 → 界面语言」,登录页右上角也能直接切。

  • 语言存在 user_settings.language,跟着账号走;未登录时按「本机 localStorage → 浏览器语言 → 中文」兜底。

  • 翻译只作用于界面文案:模板里的静态文字通过 H`...` 标记翻译,JS 里的句子用 t("中文原文", { 参数 }); 插值进去的文件名、昵称、分享标题等用户数据永远原样输出,不会被误翻。

  • 字典是「中文原文 → 译文」的普通对象(static/js/i18n/en-US.js)。漏翻的句子会原样显示中文,不会出现空白或占位符。

  • 新增语言:在 static/js/i18n.js 的 LANGS 里加一项,再建 static/js/i18n/<id>.js 字典即可(服务端 language 白名单也要加)。

  • 检查还差哪些没翻(Windows 把 .venv/bin/python 换成 .venv\Scripts\python.exe):

    .venv/bin/python scripts/i18n_check.py
    .venv/bin/python scripts/i18n_html_check.py
  • 端到端冒烟(起独立实例、中英各跑一遍并统计残留中文):

    .venv/bin/python scripts/i18n_shot.py --lang en-US
    .venv/bin/python scripts/i18n_share_shot.py --lang en-US

内置系统提示词(CDP娘的人设)也有中英两版,跟着界面语言走,但只在服务端拼装:设置页 只展示管理员自己写过的内容,内置正文不通过任何接口下发。提示词留空即用内置默认(随语言切换); 管理员自定义过的提示词属于用户内容,不会被翻译。

当前覆盖:导航与顶栏、文件列表、设置页(含看板娘对话设置)、回收站、分享、公开分享页、 关于、登录/注册/找回密码、管理后台全部页签。仅「关于 → 更新记录」的历史条目只保留中文原文。

路线图

  • M1 地基:配置、模型、认证、Fluent 主题骨架
  • M2 文件核心:目录 CRUD、搜索、拖拽上传、下载 Range
  • M3 分片上传:断点续传、秒传、并发分片
  • M4 在线预览:图片 / 视频(ArtPlayer)/ 音频 / PDF / 文本
  • M5 分享链接与回收站增强:提取码 / 次数限制 / 回收站开关
  • M7 后台管理:概览、用户、审计日志、系统设置
  • M6 WebDAV:Basic 认证、PROPFIND / PUT / MOVE / COPY / LOCK、配额与审计接入

致谢

这个项目站在一群开源项目的肩膀上:上传、预览、播放、音视频标签、看板娘渲染里最费劲的部分, 都是它们解决的。下面是运行时真正用到的依赖,与 requirements.txt、static/vendor/ 一一对应。

后端

项目 用途 许可证
FastAPI Web 框架 / 自动校验 MIT
Uvicorn ASGI 服务器 BSD-3-Clause
SQLAlchemy ORM 与数据库工具 MIT
PyMySQL MySQL 驱动 MIT
cryptography 密钥加密、证书处理 Apache-2.0 / BSD
Pillow 头像、图标与缩略图 HPND
mutagen 音视频元数据标签 GPL-2.0-or-later
qrcode 网易云扫码登录的二维码 BSD

前端(随仓库内置,不走 CDN)

项目 用途 许可证
ArtPlayer 视频 / 音频播放器 MIT
hls.js HLS 播放 Apache-2.0
dash.js DASH 播放 BSD-3-Clause
JSZip ZIP 读写(Office 预览) MIT / GPL-3.0
docx-preview Word 文档预览 Apache-2.0
SheetJS Excel 预览 Apache-2.0
PixiJS 看板娘渲染 MIT
qrcode-generator 前端二维码 MIT
Live2D Cubism SDK 看板娘模型运行时 Live2D 专有许可(非开源)

以上项目均按其各自许可证使用,完整条款见各项目仓库;Live2D Cubism SDK 不是开源软件, 使用时请遵守 Live2D 的 SDK 许可。若这份列表漏掉了你正在使用的项目,欢迎提 Issue / PR 补上。

贡献者

感谢每一位提交代码、反馈问题、改进文档的人:

完整名单与提交记录见 GitHub 的贡献者页面。 「关于」页也会从 GitHub 拉取最新贡献者(缓存 24 小时,离线时回落到内置快照)。

About

WinUI3 / Fluent Design 风格的二次元个人网盘,Python 3.14 + FastAPI 后端,零构建原生 ES Module 前端。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages