使用文档

本文档介绍 HTML 托管系统的完整使用方法。原生客户端命名：iOS「文链（手机端）」、macOS「DocLinks」。生产示例：https://docs.cn.page。

客户端命名

Web 版 /files 页面品牌为「文链 · DocLinks」；以下为 App Store 与系统显示名称，二者不可混用：

平台	App Store / 显示名称	版本	Bundle ID	用户文档
iOS 17+	文链（手机端）	1.0.2	`com.chengyusheng.docsshare.upload`	ios-app-guide.html
macOS 14+	DocLinks	1.0.1（已上架）	`com.chengyusheng.doclinks-mac`	mac-app-guide.html

iOS 勿单独使用「文链」作为 App 名称（与 Mac 端命名策略冲突）；Mac 勿在名称中加入 “Mac” 字样。

系统概述

模块	入口	用途
HTML 托管	`/`（项目目录）、`/htmls`（管理）	托管 HTML/JS/CSS 站点，多文件项目、访问密码、路径重定向
文链（Web）	`/files`	上传视频/压缩包等，生成带备注、有效期、密码的分享链接
文链（手机端）	iOS App	与 `/files` API 对齐，全屏三标签；App Store 名文链（手机端）
DocLinks	macOS App	菜单栏客户端；App Store 名 DocLinks

计算：Cloudflare Workers（Hono）
元数据：Cloudflare D1（SQLite，12 个迁移版本）
存储：Cloudflare R2
公开 URL：/p/{slug}/...、/f/{分享ID}/...

快速开始（本地开发）

npm install
npm run db:migrate:local
npm run dev

访问 http://localhost:8787/ 查看在线项目；管理台 /htmls，文链 /files。本地文档：/privacy-policy.html、/ios-app-guide.html、/mac-app-guide.html、/index.html。管理登录使用 .dev.vars 中的 ADMIN_TOKEN。

ADMIN_TOKEN=your-dev-token
# 以下可选，启用大文件 R2 直传
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...

登录成功后服务端写入 HttpOnly Cookie（htmls_admin_session），不再使用 localStorage。

部署上线

1. 创建 Cloudflare 资源

wrangler d1 create htmls-lib-db
# 将 database_id 写入 wrangler.toml

wrangler r2 bucket create htmls-lib-bucket

2. 应用数据库迁移

npm run db:migrate:remote

迁移	内容
`0001`	files 表
`0002`	projects 表
`0003`	项目访问密码字段
`0004`–`0005`	文链分享（share_groups + shared_file_items）
`0006`	app_settings（在线修改 Admin Token）
`0007`	pending_share_uploads、rate_limits（上传会话与安全）
`0008`	（保留编号；若本地曾有实验迁移请重置 D1）
`0009`	多用户表 users、user_sessions、默认配额
`0010`	share_groups.user_id 分享归属
`0011`	用户资料（display_name、phone、email）
`0012`	默认注册配额改为 50 MB

重要：未执行远程迁移时 API 会返回 503。已有环境请确保含 0012。

3. 设置 Bootstrap Token

wrangler secret put ADMIN_TOKEN

应急凭证。在线修改 Token 后，D1 中 SHA-256 哈希优先生效。

4. 配置 R2 直传（推荐）

wrangler r2 bucket cors set htmls-lib-bucket --file scripts/r2-cors.json
./scripts/setup-r2-secrets.sh

详见 R2 直传配置。

5. 部署

npm run deploy

docs/ 目录通过 wrangler.toml 的 [assets] 随 Worker 发布，包括隐私政策、客户端说明与本文档。公网示例：

/privacy-policy.html — App Store 隐私政策 URL（iOS + Mac 共用）
/ios-app-guide.html — iOS App Store 支持 URL
/mac-app-guide.html — Mac App Store 支持 URL
/index.html — 文档中心
/user-guide.html、/architecture.html — 本手册与原理文档

路由 /admin 自动重定向至 /htmls。

系统支持两种身份：

身份	入口	权限
管理员	Admin Token	HTML 托管 + 文链 + 用户管理
成员用户	用户名 / 密码（可自助注册）	仅文链分享，受存储配额限制

打开 /files：可选择「用户登录」「注册」或「管理员」Tab
打开 /htmls：仅接受 Admin Token（HTML 托管需管理员权限）
登录成功后服务端写入 HttpOnly Cookie（用户：htmls_user_session；管理员：htmls_admin_session）
后续 API 请求携带 Cookie（credentials: 'include'）
也支持 Authorization: Bearer {token}（iOS 客户端、脚本场景）
「退出登录」调用 POST /api/auth/logout 清除 Cookie

Cookie 有效期 7 天，SameSite=Lax，HTTPS 下带 Secure。

多用户与配额

用户注册

公开接口：POST /api/auth/register（用户名 3–32 位字母数字下划线，密码 ≥8 位）
可填写姓名、电话、邮箱（可选），供管理员在后台查看
新用户默认配额 50 MB（app_settings.default_user_quota_bytes = 52428800，迁移 0012）
提升配额可联系服务运营者（示例：cys@anyimail.com）或由管理员在 Web 后台调整
注册成功后自动登录并返回会话 Token

管理员分配配额

管理员登录 /files 后，页面底部「用户管理」表格可查看所有用户的姓名、电话、邮箱、空间用量，并：

创建用户并指定配额（GB）
修改已有用户的存储上限
启用 / 停用账号、删除用户

配额按用户在线分享文件总大小计算（used_bytes），上传前校验剩余空间；超额返回 413。

成员只能查看和管理自己的分享；管理员可查看全部分享。将用户 role 设为 admin 可授予与 Admin Token 等同的管理权限。

修改个人资料

成员登录 /files 后，在「我的资料」区域可修改姓名、电话、邮箱（用户名不可改），调用 PATCH /api/auth/profile 保存。iOS「文链（手机端）」与 macOS「DocLinks」设置页提供相同能力；成员可在客户端内调用 DELETE /api/auth/account 永久删除账户。

修改 Admin Token

登录后右上角「修改 Token」：

输入新 Token（≥8 字符）或点击「随机生成」
PATCH /api/auth/token 将 SHA-256 哈希写入 D1
响应同时更新 HttpOnly Cookie

修改后访客项目/分享密码 Cookie 失效，需重新输入密码。Wrangler secret 仍可作为应急登录（删除 D1 admin_token 记录可回退）。

安全说明

措施	说明
HttpOnly Cookie	管理 Token 不存 localStorage，降低 XSS 窃取风险
CSP	`/htmls`、`/files` 响应设置 Content-Security-Policy
输出转义	管理台列表渲染统一 escapeHtml，防 Stored XSS
Token 哈希	D1 仅存 Admin Token 的 SHA-256，不明文
密码加盐	新密码格式 `v2:salt:hash`，兼容旧 SHA-256
速率限制	auth/check、login、密码解锁接口按 IP 限流
恒定时间比较	Token / Cookie 校验防时序侧信道

切勿将 R2 密钥、Admin Token 写入仓库。私有部署笔记请放本地 部署.txt（已 gitignore）。

上传文件（HTML 托管）

基本上传

拖拽或选择文件到 /htmls 上传区
系统生成 8 位随机 Slug（可「随机」或手动修改）
可选填项目备注，点击「上传」

多文件 / 文件夹

支持多选或「选择文件夹」，保留相对路径
存储路径：{项目slug}/{相对路径}
上传超时 30 分钟，XHR 带上传进度

示例：Slug JvF41iat，上传 docs/index.html，入口 /p/JvF41iat 自动跳转 index。

向已有项目追加

填入已有 Slug，路径冲突时提示覆盖
备注留空保留原备注

项目管理

按项目分组，默认折叠，点击标题栏展开。支持：备注、访问密码、清除密码、复制/预览入口、删除项目。

文件操作

在线/离线：离线后公开 URL 返回 404
预览 / 复制 / 删除：单文件操作

HTML 公开访问

站点根路径 / 展示所有至少有一个在线文件的项目列表，显示项目编号（Slug）与备注；点击条目进入 /p/{slug}，若项目设置了访问密码会先弹出验证页。

地址	行为
`/`	公开项目目录（编号 + 备注）
`/p/{slug}`	入口，302 到 index.html 规范路径
`/p/{slug}/path/file.html`	直接访问指定文件

HTML 自动注入 <base target="_blank"> 与 viewport。

项目访问密码

项目组设置密码并保存
访客见密码页，验证后 Cookie 7 天有效
密码 v2 加盐哈希存储（旧数据仍兼容）
解锁接口每 IP 5 分钟最多 10 次尝试

文链（DocLinks）· 概述

分享备注、访问密码（可随机生成）、有效期预设
视频 Range 在线播放，中文文件名 RFC 5987 下载
单次最多 500 个文件，总大小上限 50 GB

大文件上传

模式	条件	单片	并发
R2 直传	R2 API 密钥 + CORS	64 MB	3 路
Worker 代理	未配密钥时回退	48 MB	1 路

上传流程

POST /api/shares/upload/init — 创建 offline 分享组，初始化 multipart，写入 pending 会话
按 clientPath 匹配本地文件，分片上传（每片最多重试 4 次）
POST /api/shares/upload/complete — 校验 pending 会话后合并
失败时自动 abort 清理 R2 multipart 与 pending 记录

页脚显示当前模式：「R2 直传」或「Worker 代理」。

分享管理

分享列表默认折叠。每条支持：改备注、有效期、密码（可随机）、在线/下线、复制链接、删除。

分享访客访问

地址	说明
`/f/{id}`	分享列表页
`/f/{id}/{路径}`	单文件（含视频流）
`POST /f/{id}/unlock`	密码验证

过期 410，下线 404。

R2 直传配置

R2 控制台创建 API Token（Object Read & Write，限定 htmls-lib-bucket）
运行 ./scripts/setup-r2-secrets.sh 或手动 wrangler secret put 三个 R2 变量
wrangler r2 bucket cors set htmls-lib-bucket --file scripts/r2-cors.json
npm run deploy，/files 页脚应显示「已启用 R2 直传」

wrangler.toml 中 R2_BUCKET_NAME 须与 R2 binding 桶名一致。

原生客户端

除 Web 版 /files 外，提供两个官方原生客户端，与同一套 API 对接。两应用均免费、无内购、无订阅。

平台	App Store 名称	Bundle ID	形态	说明文档
iOS 17+	文链（手机端）	`com.chengyusheng.docsshare.upload`	全屏三标签（上传 / 分享 / 设置）	ios-app-guide.html
macOS 14+	DocLinks	`com.chengyusheng.doclinks-mac`	菜单栏弹出面板（上传 / 已上传 / 设置）	mac-app-guide.html

App Store 必填 URL

用途	路径
隐私政策（两平台共用）	`/privacy-policy.html`
iOS 支持 URL	`/ios-app-guide.html`
Mac 支持 URL	`/mac-app-guide.html`
文档中心	`/index.html`

成员注册、登录、上传、分享管理、配额展示与 Web 版一致
分享列表采用 2×2 图标操作区（复制链接 / 分享 / 上下线 / 删除）
凭据与可选分享密码存于系统钥匙串；服务器地址存 UserDefaults
应用内「设置 → 帮助与文档」打开 {服务器}/{路径}，需先 npm run deploy 发布 docs/
成员可在设置页删除账户（永久删除账号、全部分享及 R2 文件）
iOS 特有：前台运行期间自动关闭系统锁屏；界面固定浅色模式
Mac 特有：菜单栏应用（无 Dock 图标）；启用 App Sandbox（网络客户端、用户选取文件只读）

API 接口

管理 API 鉴权方式（二选一）：

HttpOnly Cookie（浏览器管理台，推荐）
Authorization: Bearer {ADMIN_TOKEN}（脚本调用）

鉴权与用户

方法	路径	鉴权	说明
POST	`/api/auth/register`	否	成员注册，默认 50 MB 配额
POST	`/api/auth/login`	否	登录（用户或 Admin Token），设置 Cookie / 返回 Bearer
POST	`/api/auth/logout`	否	退出，清除 Cookie
GET	`/api/auth/check`	否	检查会话（限流）
GET	`/api/auth/me`	是	当前用户资料与配额
PATCH	`/api/auth/profile`	是	成员修改姓名/电话/邮箱
DELETE	`/api/auth/account`	成员	自助删除账户及全部分享（不可撤销）
PATCH	`/api/auth/token`	管理员	在线修改 Admin Token
GET	`/api/users`	管理员	用户列表（含用量）
POST	`/api/users`	管理员	创建用户
PATCH	`/api/users/:id`	管理员	修改配额/状态/资料
DELETE	`/api/users/:id`	管理员	删除用户

HTML 托管

方法	路径	说明
GET	`/api/files`	文件列表
POST	`/api/upload`	multipart 上传
PATCH	`/api/status`	更新状态 `{id, status}`
PATCH	`/api/projects/:slug`	备注 / 密码
DELETE	`/api/projects/:slug`	删除项目
DELETE	`/api/files/:id`	删除单文件

文链（DocLinks）

方法	路径	说明
GET	`/api/shares`	分享列表
PATCH	`/api/shares/:id`	更新分享
DELETE	`/api/shares/:id`	删除分享
GET	`/api/shares/upload/capabilities`	直传/代理模式
POST	`/api/shares/upload/init`	初始化分片
POST	`/api/shares/upload/part-url`	R2 预签名 URL
PUT	`/api/shares/upload/chunk`	Worker 代理单片
POST	`/api/shares/upload/complete`	合并完成
POST	`/api/shares/upload/abort`	中止并清理

公开访问

方法	路径	说明
GET	`/p/*`	HTML 项目
POST	`/p/:project/unlock`	项目密码
GET	`/f/:id`	分享页
GET	`/f/:id/*`	分享文件
POST	`/f/:id/unlock`	分享密码

常见问题

API 返回 503？

运行 npm run db:migrate:remote，确保含 0007–0012。

新用户配额不是 50 MB？

确认已执行迁移 0012；已有用户配额不会自动变更，需管理员在「用户管理」中调整。

隐私政策 URL 404？

确认 wrangler.toml 含 [assets] directory = "./docs" 并已 npm run deploy。

登录后 API 仍 401？

确认请求带 credentials: 'include'；或检查 Cookie 是否被浏览器拦截（需同域）。

大文件上传慢/失败？

配置 R2 直传 + CORS；未配置时走 Worker 代理易超时。

上传中断后怎么办？

系统会自动 abort 失败会话；重新选择文件上传即可，勿重复点击旧会话。

子目录资源 404？

从 /p/{slug} 入口访问，不要跳过 302 重定向。

修改 Token 后分享密码失效？

正常，访客 Cookie 签名密钥已变更，需重新输入密码。

本地 SQLITE_BUSY？

关闭多余 wrangler dev 进程后重启。

应用内如何删除账户？

成员登录后进入「设置 → 删除账户」，调用 DELETE /api/auth/account 永久删除账号及全部分享。管理员 Token 登录不支持此操作。详见 iOS / Mac 说明。

App Store 支持 URL 404？

确认 wrangler.toml 含 [assets] directory = "./docs" 并已 npm run deploy。完整文档列表见文档中心。

iOS 上传时屏幕自动锁定？

请保持「文链（手机端）」在前台；App 前台运行时会禁用自动锁屏，切到后台后恢复系统行为。详见 iOS 界面与显示。

使用文档

客户端命名

系统概述

快速开始（本地开发）

部署上线

1. 创建 Cloudflare 资源

2. 应用数据库迁移

3. 设置 Bootstrap Token

4. 配置 R2 直传（推荐）

5. 部署

登录与会话

多用户与配额

用户注册

管理员分配配额

修改个人资料

修改 Admin Token

安全说明

上传文件（HTML 托管）

基本上传

多文件 / 文件夹

向已有项目追加

项目管理

文件操作

HTML 公开访问

项目访问密码

文链（DocLinks）· 概述

大文件上传

上传流程

分享管理

分享访客访问

R2 直传配置

原生客户端

App Store 必填 URL

API 接口

鉴权与用户

HTML 托管

文链（DocLinks）

公开访问

常见问题

API 返回 503？

新用户配额不是 50 MB？

隐私政策 URL 404？

登录后 API 仍 401？

大文件上传慢/失败？

上传中断后怎么办？

子目录资源 404？

修改 Token 后分享密码失效？

本地 SQLITE_BUSY？

应用内如何删除账户？

App Store 支持 URL 404？

iOS 上传时屏幕自动锁定？