ulthon-doc 与代码库差异报告

生成时间：2026-07-30 对比基准：代码库 master 分支 commit 4247e8ef（2026-07-22） vs ulthon-doc project_uid=ul-disk 数据来源：README.md / CHANGELOG.md / AGENTS.md / php think list 实测 / docs/ 28 篇专题文档清单 / 17 个 ulthon-doc 页面全文 性质：只读分析报告，未修改 ulthon-doc 任何页面，未修改代码库任何文件（本报告文件除外）

---

一、整体评估

1.1 落后程度：中度不均衡

ulthon-doc 的 使用说明组（13 页）已在某次更新中刷新过，内容覆盖了 ThinkPHP 8 时代的大部分特性（Worker Pool / S3 / 限流 / 版本控制 / 公开访问 / 分享 / 域名证书等），但仍存在细节性落后与版本漂移。

真正严重落后的是 接口组（3 页）和设计原理组（3 页）——这 6 页停留在项目早期「ulthon_admin + PHP 7.4 + layui 2.7」时代，与当前 ThinkPHP 8 + FlySystem 3 + SabreDAV 4.x 架构完全脱节，其中 2 页甚至是空白或垃圾内容。

1.2 主要差距维度

维度	说明
架构描述过期	设计原理组仍描述 ulthon_admin/layui/PHP7.4/redis 分布式，实际是 ThinkPHP8/HTMX/ULUI/PHP8.4
加密算法漂移	ulthon-doc 记 AES-256-CTR + master_key；代码库已升级为 AES-256-GCM + APP_KEY 派生（per-position）
认证体系不全	缺 WebDAV 独立凭证表（WebdavCredential CR-D 范式），仅描述 admin 账号三认证
主题完全缺失	Webhook / Timer 调度 / 纠删码 / 可观测性 / 预取 / 性能基准 6 大主题无对应页面
命令覆盖不全	28 个业务命令中 9 个完全无任何页面覆盖，运维速查页仅覆盖 11 个
部署方式落后	缺根目录 docker-compose.yml 一键启动 / docker run / 自动初始化 / PowerShell BOM 警告
字段可能不符	分享管理页描述的 verify_code/expires_at/API 端点与 AGENTS.md 记载的 StorageShare 模型对不上，需核实

1.3 建议处理策略

1. 优先级 P0：重写接口组 + 设计原理组 6 页（架构性错误，误导性最强）
2. 优先级 P0：修正安全特性页加密算法（CTR→GCM）+ 认证方式页补 WebdavCredential
3. 优先级 P1：新增 6 个缺失主题页面（Webhook / Timer / 纠删码 / 可观测性 / 预取 / 性能基准）
4. 优先级 P1：补全运维命令速查页缺失的 9 个命令
5. 优先级 P2：刷新快速开始页部署方式 + 核实分享管理页字段准确性

---

二、已有页面差异（逐页对照）

2.1 接口（page_uid=62b6daa268edb，顶级 group）

ulthon-doc 现状：空页面（blocks: []），无任何内容。

代码库现状：项目有 6 个应用（admin/webdav/s3/api/raw/internal），每个都是独立协议层（README「项目结构」第 232-261 行；AGENTS.md「WHERE TO LOOK」多应用映射表）。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	空白	6 大协议层各有独立路由与控制器	P0	改写为「协议层总览」导航页，列出 WebDAV/S3/REST API/raw/internal 及对应 docs 链接

---

2.2 接口规划（page_uid=62b6dab4d7587）

ulthon-doc 现状：列出旧版接口规划——基础接口（登陆）、标准接口（节点列表/详情/创建目录/重命名/删除/上传/预览）、特殊接口（秒传/获取 chunk/分页查询）。描述「用账号密码换 token」。

代码库现状：实际协议层是 WebDAV（SabreDAV，13+ 方法）/ S3（14 操作 SigV4）/ REST（metrics/health/openapi）/ raw（公开直链）/ internal（跨节点）。无「节点列表/秒传」这类旧接口概念，文件操作通过 WebDAV/S3 协议完成。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	「节点列表/详情/创建目录节点」接口	已被 WebDAV PROPFIND/MKCOL 与 S3 ListObjectsV2 取代	P0	删除旧接口清单，改为指向 docs/s3.md + docs/api.md
2	「秒传文件」接口	实际通过 MD5 内容寻址自动去重（ChunkStorage 写入时天然秒传，无独立接口）	P0	说明去重是引擎层隐式行为，非显式接口
3	「用账号密码换 token」	实际三认证（Basic/Digest/JWT）+ S3 SigV4 + WebDAV 独立凭证 + raw 预签名	P0	重写认证描述，指向「认证方式」页

---

2.3 接口扩展开发方案（page_uid=62b9045d542af）

ulthon-doc 现状：垃圾内容（# markdown / sadf / df / gsd / > dsaf / ggggggggggggg），明显是测试乱输入。

代码库现状：无对应概念，接口扩展通过新增 app/ 子应用实现（如 s3/raw/internal 都是后加的应用）。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	垃圾测试内容	—	P0	清空重写或直接删除该页；如保留则改为「如何新增协议应用」开发指南

---

2.4 基本流程（page_uid=6333fddf82cad，设计原理组）

ulthon-doc 现状：描述「服务节点是基于 ulthon_admin 开发的 web 站点，基于 php7.4+，layui2.7+」「分布式部署必须用 redis 做共享认证」「存储节点支持 sftp/ftp/webdav/七牛云」。

代码库现状：

• README 第 116 行：框架为 ThinkPHP 8（多应用），非 ulthon_admin
• README 第 120-121 行：后台为 HTMX + ULUI（//ului.top），非 layui
• AGENTS.md 反模式 #8：禁止使用 ulthon_admin
• README 技术栈表：PHP 8.4-FPM，非 7.4
• AGENTS.md 反模式 #7：禁止引入 Swoole/Redis，用 PHP-FPM + Worker Pool 替代
• 存储驱动：Local/SFTP/FTP/WebDAV/七牛云（README 第 23 行，FlySystem 3.0）

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	「基于 ulthon_admin 开发」	ThinkPHP 8 裸写 + HTMX + ULUI（AGENTS 反模式 #8 禁用 ulthon_admin）	P0	重写为 ThinkPHP 8 多应用架构
2	「php7.4+」	PHP 8.4-FPM-bookworm（AGENTS NOTES）	P0	改为 PHP 8.4
3	「layui2.7+」	HTMX + ULUI（无构建步骤，无 JS 框架）	P0	改为 HTMX + ULUI
4	「分布式必须用 redis 共享认证」	反模式 #7 禁用 Redis；实际单管理员 + ConfigService 静态缓存 + APCu	P0	删除 redis 描述，改为 APCu + 单管理员架构
5	「mysql5.7+」	MySQL 8（think-orm 4.0，依赖 CTE 递归等 8.x 特性，trashTree 用 WITH RECURSIVE）	P1	改为 MySQL 8
6	流程图（BPMN）概念「block」	实际术语是「chunk」（4MB 分块，MD5 寻址），无「block」概念	P1	术语对齐为 chunk

---

2.5 文件原理（page_uid=63341f70434be，设计原理组）

ulthon-doc 现状：列出概念 path/chunk/position/host/chunk_position/chunk_cache。BPMN 流程图：上传→服务节点→分割临时存储→定时任务转存到存储节点→清理 chunk_cache。

代码库现状：

• 概念基本沿用（path/chunk/position），但「host」已不再使用，「chunk_position」实际表名是 storage_chunks_position，「chunk_cache」实际是 storage_chunk_cache（状态机表）
• 上传流程已重构为 ChunkStorage.writeFile + routeAndWrite + Worker Pool 三档 durability_mode（AGENTS.md「Worker Pool」节），不再是「定时任务转存」
• 写入 pipeline：明文→MD5→gzip→加密→物理存储（AGENTS.md「Pipeline 架构」）

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	「通过定时任务转存，清理 chunk_cache」	Worker Pool 三档 durability_mode（sync_one 同步写 1 副本 + 异步补；非定时任务范式）	P0	重写上传流程为 routeAndWrite + Worker Pool
2	缺写入 pipeline（加密/压缩/过滤）	pipeline：MD5→gzip→AES-256-GCM→存储（README 第 20-22 行）	P1	补 pipeline 4 步说明
3	缺 Hamming 路由说明	核心差异化：gmp_hamdist 距离路由（AGENTS.md「Hamming 路由」）	P1	补 Hamming 路由算法
4	缺多副本/纠删码	多副本（replica_count）+ Reed-Solomon 纠删码（N+M）二选一（README 第 15 行）	P1	补两种可靠性模式
5	概念用「host」	实际无 host 概念，用「服务节点/节点（node）」	P2	术语对齐

---

2.6 存储原理（page_uid=63350f7074c6f，设计原理组）

ulthon-doc 现状：描述挂载流程（BPMN）：position→检查挂载信息→遍历 chunk→标记有效/删除无效。操作：添加/挂载/自动挂载/卸载/离线健康检查/热迁移。提到「清空所有文件」「强制卸载放弃数据」。

代码库现状：

• 存储位置（position）通过 admin 后台 CRUD，无「挂载/卸载」状态机（status 只有 enable/offline，DriverFactory 直接创建 Filesystem）
• 健康检查：position:health 命令（连续 3 次失败标 offline / 3 次成功恢复 enable）
• 数据迁移：position:rebalance（超载平衡）+ position:evacuate（撤空下线），均入队 Worker Pool 异步执行，非「清空所有文件」
• 热迁移：实际是 selfheal:scan + Worker 补副本，非文档描述的「将失效 position 的 chunk 迁移」
• PositionRuntime 静态池（LRU，MAX_POOL_SIZE=100）

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	「挂载/卸载/自动挂载」状态机	无此状态机；position 只有 enable/offline，DriverFactory 即时创建 Filesystem	P0	删除挂载/卸载流程，改为 position CRUD + health 探测
2	「清空所有文件」式挂载	实际无此破坏性操作；position 接入不影响已有数据	P0	删除该描述
3	「强制卸载放弃所有数据」	无此概念；position:evacuate 是入队迁移（保留数据），非放弃	P0	改为 evacuate 迁移语义
4	「热迁移」描述	实际 selfheal:scan + Worker 补副本 + position:rebalance/evacuate（AGENTS.md「可靠性」节）	P0	重写为 selfheal + rebalance + evacuate 三命令
5	缺 PositionRuntime 静态池	LRU 池化 Filesystem 实例（AGENTS.md「PositionRuntime 静态池」）	P1	补池化机制
6	缺限流	RateLimiterService 三维度（RPM/并发/带宽）+ APCu fail-closed	P1	补限流说明（使用说明组的存储位置管理页已有，原理页应呼应）

---

2.7 使用说明（page_uid=6a3e73c598601，顶级 group）

ulthon-doc 现状：空页面（blocks: []）。

建议：作为 group 容器页，可补一段简介 + 子页面导航。

#	ulthon-doc	代码库	严重度	建议更新
1	空	—	P2	补 group 简介（一句话 + 子页面列表）

---

2.8 快速开始（page_uid=6a3e73d7dbbb9）

ulthon-doc 现状：开发栈（docker/dev）+ 生产栈（docker/prod）两种部署；端口 8002/13306/18888；配置双轨制；PHP 运行时配置表；必装扩展。

代码库现状（README 第 127-227 行）：三种部署方式——① 根目录 docker-compose.yml 一键启动（自行构建镜像 + MySQL，自动初始化 migrate+seed，端口 8001）；② docker run 单容器（自备 MySQL，需先 docker build）；③ 生产栈 docker/prod（外部 MySQL）。含 PowerShell BOM 警告、/api/health healthcheck、自动初始化说明（SKIP_AUTO_INIT=1）。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	仅开发栈 + 生产栈两种	三种（+ 根目录 docker-compose.yml 一键启动，README 主推）	P1	补一键启动方式（README 第 131-147 行）
2	缺自动初始化说明	docker-entrypoint.sh 自动 migrate+seed+写标志文件（README 第 182-191 行）	P1	补自动初始化 4 步 + SKIP_AUTO_INIT
3	缺自构建镜像说明	「镜像需自行构建，首次 10-15 分钟」（README 第 129 行）	P1	补构建时间与 build 命令
4	缺 PowerShell BOM 警告	README 第 147 行明确警告 UTF-8 BOM 破坏 docker compose 解析	P1	补 BOM 警告
5	缺 docker run 方式	README 第 149-161 行 docker run 单容器	P2	补 docker run 示例
6	缺 /api/health 端点	healthcheck 端点（CHANGELOG Unreleased；docker-compose.yml 已用）	P2	访问入口表补 /api/health
7	缺 /api/openapi.yaml	OpenAPI 规范端点（CHANGELOG 1.0.0 第 44 行）	P2	补 OpenAPI 端点
8	默认端口写 8002（开发栈）	README 主推 8001（一键/生产），开发栈才是 8002	P2	说明 8001 为生产默认，8002 为开发栈
9	缺首次使用引导	README 第 219-227 行 + docs/first-run.md + /admin/guide 引导页	P2	补首次配置 3 步引导

---

2.9 存储位置管理（page_uid=6a3e73d807b60）

ulthon-doc 现状：4 种驱动（Local/SFTP/FTP/WebDAV）+ Hamming 路由 + 容量管理 + 测速 + 限流 + 后端超时。内容较完整。

代码库现状：实际 5 种驱动（+ 七牛云，README 第 23 行）；加密为 AES-256-GCM per-position（非文档隐含的 CTR）；纠删码 N+M 二选一（文档未提）。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	驱动类型列 4 种（Local/SFTP/FTP/WebDAV）	5 种（+ 七牛云，FlySystem qiniu adapter）	P1	补七牛云驱动配置
2	缺纠删码策略	Reed-Solomon N+M 分片（与多副本二选一，per-position 策略，README 第 15 行）	P1	补纠删码位置策略
3	缺 AES-256-GCM per-position 加密	per-position 静态加密（README 第 20 行；ulthon-doc 安全特性页写的是 CTR+master_key，已过时）	P1	补 per-position 加密开关
4	缺三级优先级路由	priority → 容量 → 距离 → 权重（README 第 13 行；文档只写了 Hamming 距离路由）	P2	补三级优先级说明
5	缺 content_filter	per-position 内容过滤（mime/扩展名，README 第 22 行）	P2	补 content_filter

---

2.10 文件上传与下载（page_uid=6a3e73d827519）

ulthon-doc 现状：WebDAV + S3（14 操作表）+ 管理后台。客户端配置示例（Windows/macOS/rclone/aws-cli/boto3）。内容完整度高。

代码库现状：与文档基本一致。S3 文档说「13 个核心操作」但表格列了 14 行，与 README/CHANGELOG 的「14 操作」对齐应改文字为 14。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	文字「兼容 S3 REST API（非完整 AWS S3，13 个核心操作）」	README/CHANGELOG 明确 14 操作（含 AbortMultipartUpload）	P2	文字 13 改 14
2	缺 WebDAV 浏览器 UI 说明	/dav 同时提供现代化浏览器文件管理 UI（README 第 37 行、第 285-289 行）	P2	补浏览器 UI 截图与说明
3	缺 D14 跨区域复制说明	S3 PutObject 后入队 cross_region_task（开源版仅入队，README 第 29 行、第 61 行）	P1	补跨区域复制「仅入队」已知限制
4	缺 litmus 合规性详细结果	basic 16/16、copymove 13/13、http 4/4、props 11/14、locks 19/30（README 第 301-307 行）	P2	补完整 litmus 结果表

---

2.11 安全特性（page_uid=6a3e73d846a8a）

ulthon-doc 现状：Pipeline 架构 + AES-256-CTR 分块加密（master_key，key_id 固定 0，encryption:init）+ gzip 压缩 + content_filter + 507 容量处理。

代码库现状：

• README 第 20 行：AES-256-GCM（per-position 可选，密钥由 APP_KEY 派生）
• README 技术栈表第 124 行：加密 = AES-256-GCM（per-position 可选）
• CHANGELOG 1.0.0 第 32 行：AES-256-GCM 静态加密（per-position，APP_KEY 派生）
• AGENTS.md（commit c3920bb，6-20）仍记 AES-256-CTR——说明加密算法在 6-20 到 7-22 间从 CTR 升级到 GCM

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	「AES-256-CTR（流式，无 padding）」	AES-256-GCM（带认证标签，per-position，README+CHANGELOG 明确）	P0	算法改 GCM，补认证标签语义
2	「master_key（CSPRNG 32 字节，encryption:init）」	APP_KEY 派生（per-position，README 第 20 行）	P0	密钥模型改为 APP_KEY 派生
3	「key_id 固定 0，1 admin = 1 master_key」	per-position 可选加密（每个位置独立开关）	P0	改为 per-position 粒度
4	「IV 语义：每 chunk_md5 独立 IV」	GCM 模式 IV 语义不同（需核实源码确认 GCM 的 nonce 管理）	P1	核实并更新 IV/nonce 说明
5	encryption:init 命令	命令清单中 encryption:init 仍存在，但语义可能已变（初始化 APP_KEY？需核实）	P1	核实 encryption:init 在 GCM 模式下的行为
6	「S3 SSE 联动：x-amz-server-side-encryption: AES256」	README 第 30 行：S3 协议层 SSE 头透传，联动 per-position AES-256-GCM	P2	确认联动描述与 GCM 一致

注意：加密算法从 CTR 升级到 GCM 是 breaking change，ulthon-doc 整个「AES-256-CTR 分块加密」小节需重写。建议核实 app/common/storage/ChunkStorage.php 与 app/common/command/EncryptionInitCommand.php 源码确认 GCM 实现细节。

---

2.12 公开访问（page_uid=6a3e73d866185）

ulthon-doc 现状：/raw 路由 + 空间管理 + 预签名 + 4 层中间件（PresignedUrl/RateLimit/IpRestriction/AntiLeak）+ CORS + 回源 + Range + 安全限制。access_policy 列 public/private/locked 三态。

代码库现状：

• README 第 43 行：access_policy 为 private / public（二态，无 locked）
• AGENTS.md「W7-K 公开访问系列」：fail-closed 设计（默认拒绝，需显式 raw.enabled=1 + access_policy=public）
• docs/public-access.md / raw-presign.md / space.md / cors.md / raw-upstream.md 5 篇专题文档

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	access_policy 三态（public/private/locked）	README 二态（private/public），无 locked	P1	核实 locked 是否存在；若不存在则删除
2	缺 fail-closed 默认拒绝语义	raw.enabled=1 显式开启 + access_policy=public 双条件（AGENTS.md「W7-K」）	P1	补 fail-closed 设计说明
3	缺 docs 专题文档交叉引用	docs 有 5 篇（public-access/raw-presign/space/cors/raw-upstream）	P2	补 docs 链接

---

2.13 分享管理（page_uid=6a3e73d885793）

ulthon-doc 现状：分享功能 + 创建（后台/API）+ 访问控制（verify_code/expires_at/max_downloads）+ 数据模型表 + 配置 + HTMX 界面。API 端点 /api/share/create、/api/share/{token}。

代码库现状：

• AGENTS.md「W4-D11 分享链接」：StorageShare 表，token = bin2hex(random_bytes(16)) = 32 字符 hex；删除 = 物理删（与 AccessKey 软删不同）；明文 token 创建时只显一次
• AGENTS.md 未提及 verify_code / expires_at / max_downloads 字段（StorageShare 字段是 token / storage_path_id）
• 项目 REST API 主要是 metrics/health/openapi，是否有 /api/share/ 端点需核实*（README 未列出 share API 端点）
• docs/share.md 专题文档

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	数据模型含 verify_code/expires_at/max_downloads/download_count	AGENTS.md 只记 token/storage_path_id；其余字段需核实 StorageShare 模型源码	P1	核实 app/common/model/StorageShare.php 实际字段，修正数据模型表
2	API 端点 /api/share/create、/api/share/{token}	README API 端点表只列 metrics；share 是否有独立 REST 端点需核实	P1	核实 api 应用路由是否有 share 端点；若无则删除 API 示例
3	缺 token 生成机制	bin2hex(random_bytes(16))，CSPRNG（AGENTS.md「W4-D11」）	P2	补 token 安全生成说明
4	缺「删除=物理删」语义	与 AccessKey 软删不同（AGENTS.md「W4-D11」）	P2	补删除语义对比
5	缺与预签名 URL 的区别	docs/share.md 明确二者区别（分享 token vs raw 预签名）	P2	补对比表

注意：此页字段与端点准确性存疑，强烈建议核实源码后再更新。

---

2.14 多节点部署（page_uid=6a3e73d8a53bb）

ulthon-doc 现状：节点注册 + 心跳 + 跨节点读 + 数据再平衡（rebalance/evacuate）+ Worker Pool 三档 + 自愈扫描。内容完整度高。

代码库现状：基本一致。但需补充 D14 跨区域复制「开源版仅入队」限制。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	缺 D14 跨区域复制限制	开源版仅入队不实际跨节点物理写入（README 第 29、61 行；CHANGELOG 已知限制第 91 行）	P1	补跨区域复制「仅入队」说明
2	selfheal:verify 触发 Webhook	损坏触发 webhook（README 第 59 行：replica.degraded 事件）	P2	补 webhook 联动
3	缺 docs/multi-node.md 交叉引用	docs 有 multi-node.md + s3-cross-region.md	P2	补文档链接

---

2.15 运维命令速查（page_uid=6a3e73d8c49d9）

ulthon-doc 现状：覆盖 11 个命令（gc:expired_trash / gc:orphan_chunks / gc:stale_cache / selfheal:scan / selfheal:verify / cache:evict / worker:run / webhook:dispatch / node:register / node:heartbeat / position:benchmark）+ 推荐 cron + 仪表盘。

代码库现状：php think list 实测共 28 个业务命令（排除框架内置）。其中 9 个命令在 ulthon-doc 任何页面都未覆盖。

差异点（本页直接缺失的命令）：

#	命令	ulthon-doc	代码库说明（php think list 实测）	严重度
1	cert:render	未收录	渲染 nginx TLS 配置片段（按 bind_domain 查证书 + 替换模板）	P1
2	gc:cross_region_task	未收录	清理跨节点复制死信任务（ready/failed 超保留期）	P1
3	gc:version_enforcement	未收录	按 version.max_versions 清理超限归档版本（引用计数）	P1
4	position:health	未收录	探测后端可达性，3 次失败 offline / 3 次成功恢复 enable	P1
5	prefetch:dispatch	未收录	关联预取调度（C7，cron 每 30s，旁路限流，独立队列）	P1
6	reencode:degraded	未收录	同步立即补 erasure 分片（默认 dry-run，--force 真修复）	P1
7	replica:shrink	未收录	副本数减少后主动裁剪（保留 priority 最高的 N 份）	P1
8	space:quota	未收录	修改或查看空间配额（E5）	P1
9	timer:run	未收录	启动定时任务调度主循环（Guzzle async + 3 种 run_type）	P1

散落在其他页面覆盖的命令（本页可补入速查表）：

命令	覆盖位置
auth:token	认证方式页
domain:bind	域名与证书管理页
encryption:init	安全特性页
export:to-fs	数据迁移与SDK页
import:from-fs	数据迁移与SDK页
position:evacuate	多节点部署页 + 数据迁移页
position:rebalance	多节点部署页 + 数据迁移页
raw:presign	公开访问页

其他差异：

#	ulthon-doc	代码库	严重度	建议更新
10	「5 个 ECharts 图表」	README 第 63 行：4 图表（容量分布/协议流量/副本健康/Worker 队列）	P2	核实图表数，改为 4
11	cron 表缺 timer:run	timer:run 是调度主循环（README 第 33 行：Timer 调度）	P1	cron 补 timer:run
12	cron 表缺 prefetch:dispatch	每 30s 调度（命令说明）	P1	cron 补 prefetch:dispatch
13	cron 表缺 cert:render / position:health	证书渲染 + 健康探测	P2	按需补 cron

---

2.16 认证方式（page_uid=6a3e73d8e41c1）

ulthon-doc 现状：Basic / Digest（W4-D3，HA1 存 admin.digest_hash）/ JWT Bearer（W4-D4，auth:token）+ 认证优先级 + S3 SigV4 + raw 无认证。

代码库现状：

• README 第 28 行：WebDAV 多认证 Basic/Digest/JWT + 独立凭证表与 admin 登录密码解耦（反模式 #10）
• AGENTS.md「WebDAV 独立凭证表」：WebdavCredential 表（Basic/Digest 凭证 CR-D，无 edit；明文密码只显一次；status=revoked 软删；WebdavCredentialService::authenticate 入口）
• docs/webdav-credential.md 专题文档
• auth:token 命令说明：「生成 admin JWT token（用于 WebDAV Bearer 认证，ttl 默认 3600s）」——注意默认 ttl 是 3600s（1 小时），非文档写的 86400（24 小时）

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	缺 WebDAV 独立凭证表（WebdavCredential）	WebdavCredential CR-D 范式，与 admin 解耦（AGENTS.md「WebDAV 独立凭证表」；docs/webdav-credential.md）	P0	新增「WebDAV 独立凭证」小节
2	Digest「HA1 存 admin.digest_hash 字段」	独立凭证表后，Digest 凭证可能存 WebdavCredential 表（需核实源码确认 admin.digest_hash 是否仍用）	P1	核实 digest_hash 归属，更新字段说明
3	JWT「默认 24 小时（86400s）」	auth:token 命令实测说明「ttl 默认 3600s」（1 小时）	P1	ttl 改为 3600s
4	缺凭据中心聚合说明	admin 后台 Security 控制器聚合：admin + AccessKey + WebDAV 凭证 + raw（AGENTS.md「凭据中心」）	P2	补凭据中心导航

---

2.17 域名与证书管理（page_uid=6a3e73d90f708）

ulthon-doc 现状：domain:bind 命令 + 证书管理（W6-J9）+ nginx 模板 + 自签名证书生成。内容完整。

代码库现状：基本一致。README 第 76-77 行确认 domain:bind（监听 80/443）+ TLS 证书手动上传（openssl_x509_parse 解析 NotAfter）。docs/deploy-domain.md + tls-cert.md 专题文档。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	缺 cert:render 命令	cert:render 渲染 nginx TLS 配置片段（php think list 实测）	P2	补 cert:render 命令说明
2	缺 ACME 已知限制	ACME 自动签发属企业版 J10（README 第 77 行；CHANGELOG 已知限制）	P2	补 ACME 限制
3	缺 docs 交叉引用	docs/deploy-domain.md + tls-cert.md + https-deploy.md	P2	补文档链接

---

2.18 数据迁移与SDK（page_uid=6a3e73d931381）

ulthon-doc 现状：import:from-fs + export:to-fs + rebalance + evacuate + PHP SDK（sdk/ 目录）+ 迁移策略。

代码库现状：基本一致。README 第 78 行确认 PHP SDK 封装 WebDAV/S3/API/raw 四协议。docs/import-export.md + sdk.md 专题文档。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	SDK 示例可能简化	README 第 78 行：封装四协议（WebDAV/S3/API/raw），文档示例只展示 upload/download/delete/list	P2	补四协议完整示例或指向 docs/sdk.md
2	缺 docs 交叉引用	docs/import-export.md + sdk.md	P2	补文档链接

---

2.19 版本控制与回收站（page_uid=6a3e73d9510cb）

ulthon-doc 现状：版本控制（自动归档 + version_id 语义 + admin UI + 配置 + 已知限制）+ 回收站（软删 + trashTree CTE + 恢复 + 彻底删 + GC 关系）。内容完整度高，与 AGENTS.md 高度一致。

代码库现状：一致。docs/versioning.md + recycle.md 专题文档。

差异点：

#	ulthon-doc	代码库	严重度	建议更新
1	缺 gc:version_enforcement 命令	按 version.max_versions 清理超限归档版本（php think list 实测）	P1	补 gc:version_enforcement 说明
2	「当前仅记录元数据，不主动清理超限版本」	gc:version_enforcement 命令已实现清理（引用计数，共享 chunk 不误删）	P1	更新已知限制（已支持清理）
3	缺 docs 交叉引用	docs/versioning.md + recycle.md	P2	补文档链接

---

三、缺失主题（代码库有但 ulthon-doc 无对应页面）

以下主题在代码库 docs/ 有专题文档、README 有特性描述，但 ulthon-doc 没有任何页面覆盖：

#	缺失主题	代码库依据	严重度	建议页面位置
1	Webhook 通知	docs/webhook.md；README 第 59 行：11 处触发点覆盖 9 类事件，HMAC-SHA256 签名，两阶段投递	P0	使用说明组新增「Webhook 通知」页
2	Timer 统一调度器	docs/timer.md；README 第 33 行：Timer 调度；timer:run 命令（Guzzle async + 3 种 run_type + admin UI）	P0	使用说明组新增「定时任务调度」页
3	纠删码（Reed-Solomon）	docs/erasure-coding.md；README 第 15 行：N+M 分片，与多副本二选一；reencode:degraded 命令	P1	设计原理组「存储原理」页补充，或新增专题页
4	可观测性	docs/observability.md；X-Accel-Redirect 零拷贝 + Prometheus /api/metrics + ECharts 仪表盘 + dir_size	P1	使用说明组新增「可观测性」页
5	预取调度	docs/predictive-prefetch.md；README 第 67 行：顺序读 + 目录关联预取；prefetch:dispatch 命令	P1	设计原理组「文件原理」页补充，或新增专题页
6	性能基准	docs/performance-benchmark.md；README 第 65 行：benchmark 多维度测速	P2	使用说明组新增「性能基准」页
7	CORS 跨域	docs/cors.md；README 第 47 行：per-space CORS 规则	P2	公开访问页补充，或合并进公开访问页
8	空间管理	docs/space.md；README 第 43 行：access_policy + quota_limit；space:quota 命令	P2	公开访问页补充，或新增专题页
9	REST API 规范	docs/api.md；README 第 31 行：OpenAPI 规范 /api/openapi.yaml	P2	接口组重写时覆盖
10	生产部署检查清单	docs/production-checklist.md	P2	快速开始页或新增专题页
11	HTTPS 部署	docs/https-deploy.md	P2	域名与证书管理页补充

---

四、命令清单对照（28 个业务命令）

基于 docker exec uldisk-dev-uldisk-1 php think list 实测（commit 4247e8ef）：

#	命令	说明（实测）	ulthon-doc 覆盖	覆盖页面 / docs 文档
1	auth:token	生成 admin JWT token（WebDAV Bearer，ttl 默认 3600s）	是	认证方式页
2	cache:evict	LRU 淘汰本地读缓存 .cache（atime + max_size_gb + lru_ttl）	是	运维速查页
3	cert:render	渲染 nginx TLS 配置片段（按 bind_domain 查证书 + 替换模板）	否	docs/tls-cert.md
4	domain:bind	绑定域名与端口（更新 config + 生成 nginx 站点配置）	是	域名与证书管理页
5	encryption:init	初始化 AES-256 加密 master_key（--force 强制重生成）	是	安全特性页
6	export:to-fs	递归导出 storage_path 文件树到本地目录（只读）	是	数据迁移与SDK页
7	gc:cross_region_task	清理跨节点复制死信任务（ready/failed 超保留期）	否	docs/s3-cross-region.md
8	gc:expired_trash	清理超期回收站文件（真删，不可恢复）	是	运维速查页
9	gc:orphan_chunks	检测 + 清理孤儿 chunk（Type A 物理删；Type B 标记 corrupted）	是	运维速查页
10	gc:stale_cache	清理本地 .temp 文件缓存（默认 7 天前）	是	运维速查页
11	gc:version_enforcement	按 version.max_versions 清理超限归档版本（引用计数）	否	docs/versioning.md
12	import:from-fs	本地目录递归批量导入到 ul-disk 文件树	是	数据迁移与SDK页
13	node:heartbeat	刷新心跳 + 扫描超时节点置 offline（cron 每分钟）	是	多节点部署页 / 运维速查页
14	node:register	注册节点（host_key CSPRNG + internal_token 跨节点鉴权）	是	多节点部署页 / 运维速查页
15	position:benchmark	对 online position 写+读 4MB 测延迟，UPDATE priority	是	存储位置管理页 / 运维速查页
16	position:evacuate	撤空指定 position 的所有 chunk 副本（入队迁移）	是	多节点部署页 / 数据迁移页
17	position:health	探测后端可达性，3 次失败 offline / 3 次成功恢复 enable	否	docs/reliability.md
18	position:rebalance	扫描超载 position 并入队迁移任务	是	多节点部署页 / 数据迁移页
19	prefetch:dispatch	关联预取调度（C7，cron 每 30s，旁路限流，独立队列）	否	docs/predictive-prefetch.md
20	raw:presign	生成 raw 预签名 URL（HMAC-SHA256，ttl 默认 3600s）	是	公开访问页
21	reencode:degraded	同步立即补 erasure 分片（默认 dry-run，--force 真修复）	否	docs/erasure-coding.md
22	replica:shrink	副本数减少后主动裁剪（保留 priority 最高的 N 份）	否	docs/reliability.md
23	selfheal:scan	扫描副本数不足的 chunk 并入队补副本	是	运维速查页 / 多节点部署页
24	selfheal:verify	扫描物理副本 MD5 比对，损坏标记 corrupted + webhook	是	运维速查页 / 多节点部署页
25	space:quota	修改或查看空间配额（E5，临时 CLI，admin UI 待后续）	否	docs/space.md
26	timer:run	启动定时任务调度主循环（Guzzle async + 3 种 run_type）	否	docs/timer.md
27	webhook:dispatch	异步发送 Webhook（原子认领 + 指数退避重试）	是	运维速查页
28	worker:run	启动 Worker 主循环（认领 pending + 补副本 + max_tasks 退出）	是	运维速查页 / 多节点部署页

统计：

• ulthon-doc 覆盖：19 个（68%）
• 完全未覆盖：9 个（32%）—— cert:render / gc:cross_region_task / gc:version_enforcement / position:health / prefetch:dispatch / reencode:degraded / replica:shrink / space:quota / timer:run

注：README 第 65 行提到 benchmark:run 命令，但 php think list 实测无此命令（只有 position:benchmark）。这是 README 自身的小误差，非 ulthon-doc 问题。

---

五、建议更新优先级与工作量预估

P0 — 架构性错误 / 严重误导（建议立即处理）

任务	对应差异	工作量预估	说明
重写「基本流程」页	2.4	2-3h	ulthon_admin→ThinkPHP8、php7.4→8.4、layui→HTMX、删除 redis、术语 block→chunk
重写「文件原理」页	2.5	2-3h	删除定时任务转存、补 Worker Pool + pipeline + Hamming + 多副本/纠删码
重写「存储原理」页	2.6	2-3h	删除挂载/卸载状态机、补 selfheal + rebalance + evacuate + PositionRuntime
重写/删除「接口」「接口扩展开发方案」	2.1, 2.3	1-2h	空页补导航、垃圾页清空或删除
重写「接口规划」	2.2	1-2h	删除旧接口清单、改为协议层总览
修正「安全特性」加密算法	2.11	1-2h	CTR→GCM、master_key→APP_KEY 派生、per-position（需核实源码）
「认证方式」补 WebdavCredential	2.16	1h	新增独立凭证表小节

P0 合计：约 10-16 小时

P1 — 缺失重要主题 / 命令覆盖不全（建议近期处理）

任务	对应差异	工作量预估
新增「Webhook 通知」页	三-1	2h
新增「定时任务调度（Timer）」页	三-2	1.5h
补纠删码内容（存储原理或新页）	三-3, 2.9	2h
新增「可观测性」页	三-4	1.5h
补预取调度（文件原理或新页）	三-5	1h
运维速查页补 9 个缺失命令	2.15	2h
快速开始页补一键启动/自动初始化/BOM 警告	2.8	1.5h
存储位置管理页补七牛云/纠删码/GCM 加密	2.9	1h
文件上传下载页补 D14 跨区域限制	2.10	0.5h
多节点部署页补 D14 限制	2.14	0.5h
公开访问页核实 locked 态 + 补 fail-closed	2.12	1h
分享管理页核实字段与端点	2.13	1.5h（含源码核实）
版本控制页补 gc:version_enforcement	2.19	0.5h
认证方式页核实 digest_hash 归属 + 修 JWT ttl	2.16	0.5h

P1 合计：约 17-18 小时

P2 — 细节差异 / 交叉引用（建议 opportunistically 处理）

任务	对应差异	工作量预估
文件上传下载页 13→14 操作	2.10	5min
各页补 docs 交叉引用	多处	1h
快速开始页补 docker run / health / openapi	2.8	0.5h
使用说明 group 页补简介	2.7	10min
运维速查页图表数 5→4	2.15	5min
新增性能基准 / CORS / 空间管理 / 生产检查清单 / HTTPS 部署页	三-6~11	3-4h

P2 合计：约 5-6 小时

总工作量预估

优先级	工时	说明
P0	10-16h	架构性错误，误导性最强，必须先做
P1	17-18h	补全主要功能与命令覆盖
P2	5-6h	细节打磨与交叉引用
合计	32-40h	约 4-5 个完整工作日

---

附录 A：数据来源与核实建议

A.1 本报告依据的权威源

• README.md（commit 4247e8ef，2026-07-22）— 项目门面，最新特性列表
• CHANGELOG.md — 1.0.0 完整特性 + Unreleased
• AGENTS.md（commit c3920bb，2026-06-20）— 项目知识库，36KB（注：AGENTS.md 自身比 README 早 1 个月，加密算法仍记 CTR，以 README 为准）
• php think list 实测 — 28 个业务命令完整清单
• docs/*.md glob — 28 篇专题文档清单

A.2 建议核实源码的点（报告已标注，更新前必须确认）

1. 加密算法：核实 app/common/storage/ChunkStorage.php 加密部分 + EncryptionInitCommand.php，确认 GCM 实现与 per-position 开关
2. WebdavCredential vs admin.digest_hash：核实 app/common/model/WebdavCredential.php + app/common/service/WebdavCredentialService.php，确认 Digest 认证当前走哪个表
3. StorageShare 字段：核实 app/common/model/StorageShare.php，确认是否有 verify_code/expires_at/max_downloads 字段
4. /api/share/ 端点*：核实 app/api/route/route.php，确认是否有 share REST 端点
5. access_policy locked 态：核实 app/common/model/StorageSpace.php，确认是否有 locked 枚举值
6. ECharts 图表数：核实 app/admin/view/index/_dashboard.html，确认是 4 还是 5 个图表容器

A.3 未覆盖说明

• 本报告未逐字读取 docs/ 下 28 篇专题文档全文（token 预算考虑），而是通过 README 文档索引 + AGENTS.md「WHERE TO LOOK」映射表确认每篇 doc 的覆盖范围。如需逐句核对某篇 doc 与 ulthon-doc 对应页的差异，建议单独读取该 doc 全文。
• ulthon-doc 的 BPMN 流程图（基本流程/文件原理/存储原理页各 1 个）内容已读取，但因其描述的旧架构整体过时，未逐节点分析 BPMN 差异，建议重写时整体替换。

---

报告结束。本报告仅用于差异分析，未修改 ulthon-doc 任何页面，未修改代码库任何文件。