自托管的二次元个人网盘 · WinUI 3 / Fluent Design 风格 · 文件只放在你自己的机器上
Python 3.14 + FastAPI 后端,零构建原生 ES Module 前端;分片秒传、在线预览、分享链接、WebDAV、管理后台与看板娘 AI 助手一应俱全,多用户各占独立空间与配额。
- 文件管理:目录树、网格 / 列表双视图、多选(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。
镜像里已经带好 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 build3. 打开
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,而容器里跑的是 uid10001。 执行一次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 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=xxxxxLYRICS_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=。
管理后台 → 系统设置 → 网易云歌词 → 扫码登录,用网易云音乐 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 的同名变量优先级更高,不会被文件覆盖。
界面支持 简体中文 / 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 |
| 项目 | 用途 | 许可证 |
|---|---|---|
| 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 补上。
感谢每一位提交代码、反馈问题、改进文档的人:
- @minecraftmc22 — 作者与维护者
完整名单与提交记录见 GitHub 的贡献者页面。 「关于」页也会从 GitHub 拉取最新贡献者(缓存 24 小时,离线时回落到内置快照)。








