单管理员、自托管、低维护成本的文件分享工具。
文件保存在自有服务器的磁盘上;管理端使用统一的文件夹树、文件预览与分享管理,公开访客通过 /s/<token> 浏览或下载被分享的内容。
- 统一的嵌套文件夹树;文件和文件夹都在同一个浏览器中上传、搜索、排序、移动、重命名、删除和分享。
- 同一父目录下名称唯一;上传或重名时自动生成
name (2)一类名称。 - 支持拖拽上传、分页、搜索、名称/大小/时间排序、列表/网格视图、多选和 ZIP 打包下载。
- 支持从外部链接导入文件到指定目录;下载端使用已解析并校验过的 IP,禁止代理环境绕过地址校验。
- 图片、音视频和文本预览;常见文本和代码文件可在浏览器内编辑。
- 文件与文件夹使用统一的分享模型,可设置编辑权限、可选密码和可选过期时间。
- 分享管理页可查看全部链接、修改权限/有效期/密码、复制链接、显示二维码并撤销。
/s/<token>同时处理文件和文件夹分享;旧/f/<token>会重定向到同一页面。- 桌面侧栏、面包屑、工具栏和移动端抽屉导航;保留中文界面、深浅色主题。
- 可选 WebDAV 双向同步,远端路径以文件 ID 为稳定标识。
要求 Python 3.10+、Node.js 18+ 和 npm。
./start.sh脚本会创建 backend/.venv、安装依赖、构建前端,然后由 Uvicorn 在 8000 端口同时提供 API 和前端。开发时使用:
./start.sh --devcd frontend
npm ci
npm run build
cd ../backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000首次启动会创建 backend/data/cryovault.db 和 backend/data/storage/。新建安装不需要迁移旧数据。
CRYOVAULT_PANEL_PATH 为空时,管理端可从 /login 和 /files 访问;设置随机面板路径后,管理端位于 <panel-path>/files,根路径返回 404。分享页始终使用公开的 /s/ 地址。
一键脚本适用于支持 systemd 的 Linux:
bash <(curl -fsSL https://github.com/HlONGlin/CryoVault/raw/main/one-click.sh)脚本进入交互菜单,支持安装/更新、启停、卸载、重置管理员令牌和重新生成面板路径。默认位置如下:
| 内容 | 路径 |
|---|---|
| 程序 | /opt/cryovault |
| 数据、SQLite 数据库、文件存储和配置 | /var/lib/cryovault |
| systemd 单元 | /etc/systemd/system/cryovault.service |
脚本会创建 cryovault 系统账号并用于数据文件所有权,但当前生成的 systemd 单元没有 User=,因此服务进程实际以 root 运行。这是为了让网页内更新能够执行安装、写入 /opt/cryovault 并重启系统服务。网页更新会以 root 执行从配置的 GitHub 仓库拉取的安装脚本,只应在信任该更新来源时启用 CRYOVAULT_UPDATE_ENABLED。
start.sh 的用法保持不变;本次重构没有删除或重命名现有环境变量。
升级会修改 SQLite 元数据,但不会移动或重命名 storage_dir 中的已存文件。应用在首次执行 v0.3.0 迁移前,会用 SQLite backup API 创建与数据库同目录的备份:
cryovault.db.pre-v0.3.0-YYYYMMDDTHHMMSSZ.bak
仍建议在升级前对整个数据目录做独立备份,并先在副本上演练。systemd 安装可以执行:
sudo systemctl stop cryovault
sudo cp -a /var/lib/cryovault "/var/lib/cryovault.pre-v0.3.0-$(date +%Y%m%d-%H%M%S)"
sudo systemctl start cryovault然后通过一键脚本选择“安装或更新”,或在已校验的源码目录执行部署流程。升级后应检查:
/api/health返回0.3.0。- 管理端文件树可以浏览原有文件;原系统分组中的文件位于根目录。
- 旧
/s/<token>、/f/<token>、/api/share/<token>和/api/file-share/<token>链接仍有效。 - 分享管理页能显示旧分组和旧文件分享,权限与 token 没有变化。
- 启用了 WebDAV 时,先检查同步设置和日志,再执行一次手动同步。
迁移规则:
- 每个旧非系统
Group转为根目录下同名Folder;重名会自动编号。 - 原系统分组中的文件转为根目录文件。
- 旧
Group.share_token和FileShare.share_token原样写入统一Share,不会重新生成 token。 - 旧分组
description保存在Folder.description。 - 旧
Group、FileShare和映射表只为兼容旧 API 保留;新界面和公开页只通过统一树与分享模型工作。
不要只恢复数据库而忽略升级后新增的文件。安全回滚方式如下:
sudo systemctl stop cryovault
sudo cp -a /var/lib/cryovault "/var/lib/cryovault.after-v0.3.0-$(date +%Y%m%d-%H%M%S)"
sudo rm -rf /var/lib/cryovault
sudo cp -a /var/lib/cryovault.pre-v0.3.0-YYYYMMDD-HHMMSS /var/lib/cryovault
# 将 /opt/cryovault 恢复到 v0.2.2 程序
sudo systemctl start cryovaultafter-v0.3.0-* 目录保留升级后的数据库与文件,必须先保留它再恢复旧快照。也可以只替换迁移前数据库备份,但升级后新增或修改的文件不会出现在 v0.2.2 数据库中;需要从升级后的完整备份单独取回。
前端路由:
| 路由 | 用途 |
|---|---|
/files/:folderId? |
统一文件树 |
/shares |
分享管理 |
/settings |
WebDAV、更新与设置 |
/login |
管理登录 |
/s/:token |
文件/文件夹公开分享 |
/f/:token |
旧文件分享兼容重定向 |
管理 API 统一使用当前登录会话。核心接口:
| 方法 | 路径 | 用途 |
|---|---|---|
POST |
/api/admin/session |
用 X-Admin-Token 换取短期 HttpOnly 会话 |
DELETE |
/api/admin/session |
服务端吊销当前会话 |
GET |
/api/folders?parent_id=&page=&page_size=&sort=&order=&q= |
列出目录内容 |
POST |
/api/folders |
新建文件夹 |
GET |
/api/folders/{id} |
文件夹、面包屑与子树统计 |
PATCH |
/api/folders/{id} |
重命名或移动文件夹 |
DELETE |
/api/folders/{id} |
递归删除文件夹 |
POST |
/api/files |
上传一个或多个文件到 folder_id |
POST |
/api/files/import |
从 URL 导入到指定目录 |
POST |
/api/files/archive |
将选中的文件/文件夹打包为 ZIP |
PATCH |
/api/files/{id} |
重命名或移动文件 |
DELETE |
/api/files/{id} |
删除文件 |
GET |
/api/files/{id}/download |
下载;支持 Range |
GET |
/api/files/{id}/raw |
内联读取;支持 Range |
GET |
/api/files/{id}/content |
读取可编辑文本和 ETag |
PUT |
/api/files/{id}/content |
用 ETag 乐观锁保存文本 |
GET |
/api/shares |
列出全部分享 |
POST |
/api/shares |
为文件或文件夹创建分享 |
PATCH |
/api/shares/{id} |
修改编辑权限、过期时间和密码 |
DELETE |
/api/shares/{id} |
立即撤销分享 |
GET |
/api/public/shares/{token} |
获取公开分享信息 |
POST |
/api/public/shares/{token}/unlock |
校验分享密码 |
GET |
/api/public/shares/{token}/folders |
浏览分享文件夹子树 |
GET |
/api/public/shares/{token}/files/{id}/download |
下载分享文件 |
GET |
/api/stats |
全局文件数与占用空间 |
GET |
/api/health |
运行版本与健康检查 |
创建分享的请求示例:
{
"target_type": "folder",
"folder_id": 12,
"allow_edit": false,
"expires_at": "2026-12-31T23:59:59Z",
"password": "optional-password"
}公开文件夹 API 的每个请求都重新验证分享状态、密码 cookie、过期时间以及目标文件夹是否仍在分享根目录子树内。共享 token 本身不等于任意节点访问权限。
兼容接口 /api/share/...、/api/file-share/...、/api/groups/... 和 /api/direct/... 保留用于旧客户端;新前端不再调用这些入口。
配置文件示例见 backend/.env.example。常用变量:
| 变量 | 默认值 | 说明 |
|---|---|---|
CRYOVAULT_DATA_DIR |
./data |
SQLite、共享文件和迁移备份所在目录 |
CRYOVAULT_BASE_URL |
http://localhost:5173 |
生成公开链接时使用的外部地址 |
CRYOVAULT_ADMIN_TOKEN |
空 | 管理令牌;留空时管理 API 不要求认证 |
CRYOVAULT_MAX_UPLOAD_SIZE |
0 |
单文件上限,0 表示不限制 |
CRYOVAULT_MAX_TEXT_EDIT_SIZE |
5242880 |
浏览器文本编辑器的最大字节数 |
CRYOVAULT_SESSION_MAX_AGE |
2592000 |
管理会话有效期,单位秒 |
CRYOVAULT_COOKIE_SECURE |
false |
HTTPS 部署应设为 true |
CRYOVAULT_PANEL_PATH |
空 | 管理端随机路径,例如 /panel/随机值 |
CRYOVAULT_DOCS_ENABLED |
false |
是否公开 /docs 与 /openapi.json |
CRYOVAULT_TRUST_PROXY_HEADERS |
false |
仅在可信反向代理后开启 |
CRYOVAULT_CORS_ORIGINS |
[] |
额外允许的前端来源 |
CRYOVAULT_UPDATE_ENABLED |
false |
是否允许网页执行安装脚本 |
CRYOVAULT_UPDATE_COMMAND |
空 | 仅允许安装目录内的一键脚本 |
CRYOVAULT_WEBDAV_ENABLED |
false |
是否启动定时双向同步 |
生产环境至少设置长随机管理员令牌、随机面板路径和 CRYOVAULT_COOKIE_SECURE=true,并通过 HTTPS 暴露服务。若管理员令牌为空,应用仍会启动,但会输出明显安全警告,且管理 API 对能访问服务的人开放;不要以这种状态监听公网。
依赖说明:固定 httpcore==1.0.9,是因为外链导入需要让 TLS 连接真正使用已经完成公网地址校验的解析结果,避免校验与实际连接之间的 DNS 重绑定窗口。项目没有引入 ORM 或迁移框架等重型新依赖;版本化迁移使用现有 SQLAlchemy 与 SQLite schema_version 表。
WebDAV 设置保存在数据库中,密码由服务端加密保存且不会通过 API 返回。现有 v0.2.2 SyncState 行会保留,旧 groups/<group-id>/<file-id>-<name> 路径继续映射原文件,不会因升级自动重复上传或删除。
- 新文件使用
files/<file-id>-<name>;文件 ID 在目录移动后保持不变,因此文件夹移动不会触发远端搬家。 - 文件重命名会安全 MOVE 旧远端对象到稳定新路径,并立即保存新路径。
- 无法由本地文件 ID 认领的远端未知文件会保留并记为跳过,不会被静默删除。
- 远端删除、冲突和本地提交失败都有测试覆盖;本地文件替换采用暂存文件,数据库提交成功后才删除旧文件。
- 升级前仍应备份整个数据目录。升级后先执行手动同步并检查报告;若有异常,停止服务、保存升级后数据,再按上面的回滚步骤处理。
WebDAV 继续支持设置页中的连接测试、状态与手动运行。服务只应由单个进程运行,避免两个调度器同时修改同一数据。
后端:
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest -qWindows PowerShell:
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
python -m pytest -q前端:
cd frontend
npm ci
npm run typecheck
npm run buildGitHub Actions 会在推送和拉取请求上分别执行 pytest、TypeScript 检查和前端生产构建。
CryoVault/
├─ backend/
│ ├─ app/
│ │ ├─ routers/ # 管理会话、文件夹、文件、分享、同步和更新 API
│ │ ├─ models.py # Folder/FileItem/Share 及兼容旧 token 的数据表
│ │ ├─ database.py # schema_version、幂等迁移与迁移前备份
│ │ ├─ operations.py # 原子保存、唯一命名、文本编辑和树操作
│ │ ├─ webdav.py # WebDAV 客户端、映射和同步调度
│ │ └─ main.py # FastAPI 应用与按需加载的 SPA 静态托管
│ ├─ tests/ # pytest 回归测试
│ ├─ requirements.txt
│ └─ requirements-dev.txt
├─ frontend/
│ └─ src/
│ ├─ api/ # 唯一 API 客户端和类型
│ ├─ components/files/ # 统一文件浏览器视图与对话框
│ ├─ hooks/ # 目录、上传和选择状态
│ ├─ pages/ # Files、Shares、Settings、登录和公开分享页
│ └─ components/Layout.tsx
├─ docs/
│ ├─ ARCHITECTURE.md
│ └─ REFACTOR_PLAN.md
├─ .github/workflows/ci.yml
├─ scripts/sync_version.py
├─ start.sh
└─ one-click.sh
- 管理员令牌只在登录请求的
X-Admin-Token头中发送一次;成功后签发随机、服务端可吊销的 HttpOnly 会话。每次登录生成新值,锁定与更换令牌会使旧会话失效。 - 会话保存在进程内,因此服务重启会注销所有管理员,当前部署只支持单进程。
- 文件以明文保存在
storage/;CryoVault 不宣称本地加密或端到端加密。WebDAV 凭据会加密保存,但文件本身仍由远程存储服务管理。 - 分享密码使用 PBKDF2 哈希。修改密码、撤销分享或到期会阻止后续访问;文件编辑同时受分享权限和 ETag 校验保护。
- API、上传、会话与错误处理都有回归测试。不要在容器中禁用提权后仍开启网页更新;这种情况下请由宿主机管理员运行更新脚本。
- 回收站、断点续传、多用户/角色、对象存储和存储配额不在本版本范围内。
- 在线编辑的进程内锁不覆盖多进程部署;请保持单 Uvicorn worker。ETag 可防止正常并发覆盖,但进程崩溃期间的文件与数据库一致性没有事务级保证。
- 管理员会话和登录限流状态在进程内,重启会失效或清空。
- 一键部署的更新链路需要服务以 root 运行,存在 GitHub/分支内容受信任边界;本次只如实记录,未扩大更新权限。
- 当前仓库没有声明许可证;公开发布或二次分发前应补充许可证文件。