From 08598713637b3cb0606ca39e04e4fb1b1a58e3da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=B8=A1=E5=8F=A3=E6=B5=AA=E4=BA=BA?=
 <maintainer@example.com>
Date: Fri, 23 Oct 2026 23:47:52 +0800
Subject: [PATCH] docs: audit commercial readiness and security gaps

---
 docs/COMMERCIAL_AUDIT.md | 173 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 docs/COMMERCIAL_AUDIT.md

diff --git a/docs/COMMERCIAL_AUDIT.md b/docs/COMMERCIAL_AUDIT.md
new file mode 100644
index 0000000..21b9592
--- /dev/null
+++ b/docs/COMMERCIAL_AUDIT.md
@@ -0,0 +1,173 @@
+# 商业化审计（2026-10-23）
+
+审计基线：`ed3b61b`，版本 0.1.29。目标定位为单用户、自托管、多终端图片服务；不把多租户、微服务或复杂权限系统作为当前必需项。本次审计不修改业务、不执行设备写入、不删除生产数据。
+
+## 结论
+
+当前“照片来源 → 来源图库 → 多个生成方案 → 终端绑定单个来源及方案”的模型合理，适合继续发展；来源画面、生成版本、上传回执、设备实际显示状态分开管理也是正确的。无需重写技术栈。
+
+当前适合受控内网使用和继续迭代，尚不能据此宣布达到面向外部客户的商业交付标准。主要差距集中在依赖安全、传输安全、上传流程闭环、存储失败一致性和产品表达统一。未发现经过验证的未授权接管或数据外泄事件；也不据此声称不存在其他漏洞。
+
+优先级：P1 为对外交付前处理；P2 为下一轮产品完善；P3 为演进建议。以下“确认”指代码或本地复现已证实，“风险”表示存在可解释路径但没有执行攻击或故障压测。
+
+## 一、对外交付前的问题
+
+### A01 · P1 · 锁定依赖存在新公开安全告警（确认，利用条件需分别判断）
+
+`requirements.lock:4,11,13` 固定 certifi 2026.7.22、opentelemetry-api 1.45.0、Pillow 12.3.0。本次 `pip-audit -r requirements.lock` 返回非零：3 个包、37 条告警，其中 Pillow 35 条。不能把这个数字等同于 37 个可利用的应用漏洞。
+
+已核对公告及代码路径：
+
+- Pillow 的 PNG EXIF 解析复杂度问题关联当前允许的 PNG 输入，以及 `renderers/images.py:30` 后的 `ImageOps.exif_transpose()`、`display/libraries.py:178` 后的 EXIF 读取。文件和像素上限不能充分限制元数据解析耗时。[公告](https://github.com/advisories/GHSA-g4qv-2jxx-769h)
+- XBM 解析告警发生于 `Image.open()` 内；当前在打开之后检查格式，不等于阻止识别阶段调用其他插件。建议所有不可信图片入口明确传入允许的 `formats`，再做格式、像素和字节检查。[公告](https://github.com/advisories/GHSA-xgh8-jp6q-p5x8)
+- certifi 告警涉及被撤销的中间证书对应信任链，影响使用该 CA 包且攻击者能够干预网络的 TLS 请求；NAS 指纹固定路径不能代表所有外部 HTTPS 路径均受同等保护。[公告](https://github.com/advisories/GHSA-6q48-6c7w-9gw2)
+- OpenTelemetry 告警涉及特定 tracestate 解析路径，本次没有证明项目启用了对应的入站解析，不将其写成已证实远程攻击面。[公告](https://github.com/advisories/GHSA-xcq7-p3pf-p88h)
+
+建议：先升级有修复版本且兼容的依赖、重建镜像，再逐条确认剩余公告可达性。扫描建议版本包括 certifi 2026.10.19、OpenTelemetry API 1.45.1、Pillow 13.0.0；不是未经兼容验证的直接升级指令。部分公告没有给出修复版本，需要限定输入路径或记录有依据的暂缓项。验收要求是锁文件与镜像一致、关键渲染回归通过、告警逐条有处置结论。
+
+### A02 · P1 · 当前管理入口使用 HTTP（确认）
+
+实际访问入口使用 HTTP，线上可读取 `/ready`。`core/accounts.py` 根据请求 scheme 决定 Cookie 的 Secure 标志，HTTP 登录不会得到 Secure Cookie。密码、会话和家庭照片在该网络段缺少传输机密性；这是部署安全边界，不能只靠密码哈希解决。
+
+建议商业交付通过 HTTPS 入口服务；明确可信反向代理、转发协议和 Origin 配置，验证登录、CSRF、Cookie Secure、HTTP 跳转后再按域名条件启用 HSTS。不要直接改转发头信任而扩大来源伪造风险。验收包含整个会话的 HTTPS，而不只是登录页。
+
+### A03 · P1 · 手动上传没有接入新图库闭环（确认）
+
+`web/app.js:126` 的“仅保存到本地图库”仍执行设备 upload 操作；成功提示“已保存到服务器，可用于模板与任务”。该资产不等于 `source_images` 中的来源图片，当前来源/终端图库也不是通用 assets 浏览器。移除旧图库后，新用户无法按按钮承诺的位置找回这类图片。
+
+建议采用明确的“手动上传来源”，保存后走现有来源入库及方案流程；或先将入口准确命名为“保存为模板素材”，提供可访问的素材管理入口。不要再引入一个没有生命周期定义的第三套图库。验收：上传、保存、刷新、离开重进、按方案生成、终端使用均能找回同一图片。
+
+### A04 · P1 · 文件与多表数据变更缺乏完整失败一致性（代码确认，故障损失量未测试）
+
+`renderers/images.py:86` 先写文件再插入 assets；`display/libraries.py:166` 入库和 `:310` 生成分别提交资产、来源或版本及溯源记录。`remove_asset():645` 先 unlink，再逐表删除。`storage/database.py:79` 单次 execute 提交，不会自动把整个业务操作合成事务。进程退出、磁盘满、SQL 失败可能留下孤儿文件/记录，删除中断也可能留下指向缺失文件的记录。
+
+建议复用现有 transaction，覆盖一个业务动作的数据库变更；文件采用临时文件及失败补偿，删除流程记录可重试状态。数据库事务不能回滚文件，因此两者都要处理。无需为此引入分布式事务。验收应注入一次写文件失败、一次 SQL 失败及一次删除中断，并验证可恢复或可清理，不误删仍被任务/终端引用的资产。
+
+### A05 · P1（商业使用时）· 外部服务商业授权边界未完成（确认存在约束）
+
+项目 MIT 许可和第三方 NOTICE 已有基础；但 `NOTICE.md` 明确 Open-Meteo 公共 API 按家庭非商业部署使用，商业部署需重新审查服务条款。开源项目许可证不能替代外部天气 API、厂商账号/API 及品牌使用授权。
+
+建议在出售或收费托管前确认所启用服务的商业套餐、额度、品牌说明和数据使用边界；不需要启用的可选服务默认关闭。此项不是法律合规认证，也不意味着现有家庭使用已经违规。
+
+## 二、安全与权限
+
+### A06 · P2 · 图片写入权限无法单独授予（本地复现）
+
+`core/auth.py:14` 的 ALL_SCOPES 缺少 `images:write`，而 `api/app.py:363,672,693` 要求该权限。`extensions/api.py:234` 拒绝未知权限。
+
+隔离 Mock 实测：创建 `images:read` 客户端返回 201；同结构创建 `images:write` 返回 400 / `Unknown permission scope`。管理员可使用接口，但最小权限集成被迫使用更宽权限。这是权限目录与接口契约不一致，不是已证实的越权。
+
+建议统一权限注册表，并测试所有 require(scope) 均可被授权，前端选项与 OpenAPI 使用同一来源。
+
+### A07 · P2 · 登录计算占用共享数据库锁（风险）
+
+`core/accounts.py:110` 附近登录函数在 `with db.lock` 中执行 scrypt，包括不存在的用户名。数据库线程共用 RLock，慢密码计算会阻塞其他需要该锁的操作。已有 IP 和账号失败限流有效降低重复尝试，但不消除并发或分散用户名的资源消耗。
+
+建议将昂贵校验移到锁外，短事务更新尝试次数；必要时限制并发认证数量。验收使用本地少量并发请求，验证正常读取和调度不被明显拖慢。本次未向生产发送压力请求。
+
+### A08 · P2 · 商业账号能力还需补齐（设计差距）
+
+已有安全哈希、登录限流、CSRF、退出和改密撤销会话。会话目前为固定绝对过期（12 小时或记住 30 天），没有空闲过期和会话列表/逐个撤销界面。单用户是明确需求，应保留；可增加“其他设备退出”和可信恢复流程，无需引入用户组织体系。
+
+密码至少 8 位符合当前用户要求。若面向单因素商业登录，应重新确定最低长度、弱密码拦截和可选第二因素，而不是未经确认改现有规则。NIST 当前指导中单因素最低 15 位、多因素中的密码最低 8 位，可作为产品策略参考，不据此宣称项目违法。[NIST](https://pages.nist.gov/800-63-4/sp800-63b.html)
+
+### A09 · P2 · CSP 仍允许 inline script 和外部 CDN（确认）
+
+`api/app.py:227` 允许 script-src unsafe-inline 及 jsDelivr，虽然 Swagger 已本地化。这削弱注入后的防护边界；本次未证明存在 XSS。建议盘点实际 inline 需求后移除多余域名，并逐步使用独立脚本或 nonce；不要未经验证一次性收紧导致界面失效。
+
+## 三、数据模型与架构
+
+### A10 · P2 · 当前名称与生成快照应持续明确区分（已有改善，需约束）
+
+`display/libraries.py:236` 版本列表已集中关联当前方案名称，同时保留生成时 plan 快照、原存储名称及参数一致性标记。方案改名不应篡改历史参数，也不应导致重新生成；参数改变则应产生新版本。这一方向正确。
+
+后续必须保持：关联使用稳定 ID；列表显示当前名称；历史参数明确标注生成时；下载文件名与物理文件名可以不同。建议把这套展示对象复用于图库、详情、任务和下载，避免各页自行读取 payload.name。代码抽查与现有回归不等于对所有历史数据库状态的完整证明。
+
+### A11 · P2 · 数据关系主要依赖应用维护（确认）
+
+SQLite 表存在跨表 ID 引用，但未形成统一外键/迁移版本体系，结构初始化和演进分布在模块中。单实例 SQLite 对当前规模合理；问题是关系变化后，删除/迁移/清理更依赖人工枚举引用。
+
+建议新增结构版本和小型可重复迁移机制，逐步明确来源、方案、版本、资产、任务、回执的删除约束；先检查已有数据再决定增加外键，不强行一次重构所有表。保留用于幂等和当前状态判断的回执，不能因“历史”标签就删除。
+
+### A12 · P2 · 容量与运行边界未形成交付承诺（风险）
+
+进程内锁、单 Uvicorn worker、SQLite 和本地文件适合单实例；不能直接扩为多个副本共享同一目录。缓存有界不代表长期来源资产及多方案版本有界。当前未建立客户可见的存储水位、版本清理规则和满盘处理闭环。
+
+建议先公布单实例支持边界，加入磁盘余量提示和可预览的按引用清理，不需要立即更换数据库或增加队列。商业验收补充典型 NAS 库、并发预览及长任务下的响应时间、峰值内存和满盘行为。
+
+## 四、导航、UI 和关键流程
+
+### A13 · P2 · 一级导航职责需要分组（设计审计）
+
+桌面当前 12 个平级入口将核心操作、创作工具和系统管理混在一起。“来源图库”和“照片数据源”有真实职责差异，但新用户需要先理解；“模板”和“拼版与海报”也缺少关系解释。
+
+建议保留现有页面，按“图库 / 创作 / 运行 / 管理”分组；来源图库负责照片及输出，照片数据源负责 NAS/网盘连接和筛选规则，连接中心负责外部服务凭据。首次流程以“连接来源 → 选入照片 → 方案 → 绑定终端 → 查看结果”串联。避免只改菜单名、不改页面职责。
+
+### A14 · P2 · 全局设备选择器与图库局部终端选择重复（确认，认知风险）
+
+全局 shell 仍选择设备，终端图库又以标签选终端；来源图库不依赖某个终端却同样显示全局设备。手表无传输能力时，“设备/相框/终端”容易混用。
+
+建议只在依赖目标设备的页面显示全局目标，或统一由终端图库标签控制，并明确设备与手表输出档案的能力区别。所有按钮都依据能力显示状态和原因；“已生成、已上传、已在终端显示”继续分开，不能将操作成功等同于实物屏幕已显示。
+
+### A15 · P2 · 文案和本地图库旧概念仍残留（确认）
+
+`web/app.js` 上传页和 `web/i18n.js` 的 staging、uploadNotice 等仍表达“本地图库”，但当前用户模型已转为来源图库/终端图库。多个词典覆盖和页面内 tr() 分散维护，增加中英文错位的机会。
+
+建议统一术语：照片数据源、来源图片、生成方案、成品版本、终端；为保存、生成、上传、显示分别定义动作词。将重复文案收敛到现有词典，不必更换前端框架。验收覆盖中英文按钮、禁用原因、错误提示、空状态、确认框和帮助文本。
+
+### A16 · P2 · NAS 分页筛选不是完整全库索引搜索（确认）
+
+`providers/source_browser.py:196` 每次最多读取 4 批，每批默认 36 条，再对多项条件本地筛选；人物等可利用提供方能力。这个设计保护响应时间，但筛选后当前页为空并不等于整个 NAS 没有符合结果；也没有准确的匹配总数。
+
+建议明确“本批未找到，可继续扫描”，显示已扫描量和继续状态；需要全库快速定位时优先使用提供方原生搜索能力，仅在需求明确且测量后考虑持久索引。不能为了准确总数回到每次扫描整库。验收至少包括跨多批才命中的筛选、空批后继续、筛选变化重置游标和重复/漏项检查。
+
+### A17 · P2 · 移动端与无障碍覆盖还不够完整（部分验证）
+
+本次在 1440×1000、390×844 打开来源图库、终端图库、上传、设置页面，未发现 document 横向溢出；这些页面 main 内 input/select 的关联标签抽查无缺失。截图确认基础配色、圆角和按钮体系统一，移动端会将导航变为底部条。
+
+但上述仅为隔离 Mock 的部分页面，其中来源图库为空状态，不是全部真实卡片/数据/错误状态验证。移动导航入口较多，发现性与滚动提示还需用户验证；未完成屏幕阅读器、全键盘任务链、对比度量测、长方案名和全部弹窗矩阵。不能据此声称 WCAG 合规。建议保留当前视觉系统，补任务级测试和可见焦点，不做纯审美重绘。
+
+## 五、交付、运维、隐私和维护
+
+### A18 · P2 · 运维基础有，但缺少客户服务级证据（部分确认）
+
+已有 /health、/ready；/ready 检查 SQLite、设备配置、调度器和认证，不能误称只有进程存活检查。当前线上四项均正常。还需客户可理解的磁盘/供应商不可用提示、脱敏诊断导出、关键任务失败通知和明确支持边界。
+
+代码和版本可恢复不等于数据库、凭据、设备绑定和方案数据可恢复。当前遵循项目“不保留备份”的明确运维选择，本次不创建或修改备份策略；商业交付前需明确该选择对应的数据丢失承诺与恢复责任。
+
+### A19 · P2 · 隐私和数据生命周期需要面向用户表达（交付差距）
+
+照片、人物名称、日期位置以及 NAS/厂商账号均属于需要清晰说明的数据。应说明哪些数据留本地、哪些请求发给哪个服务、预览与源文件的区别、删除是否涉及 NAS 原文件/设备云端、保留期限及账号撤销方式。已有 SSRF、凭据脱敏和证书指纹措施有价值，但不能替代用户可理解的说明。本次未作法律合规认证或外部供应商全面审计。
+
+### A20 · P3 · 前端全局状态与大型模块增加改动风险（确认结构，非重写理由）
+
+`web/app.js`、`web/libraries.js`、词典和追加 CSS 依赖共享 state/全局函数，部分页面模板为很长单行；后端 app/service 也承载较多职责。现有按领域拆分 providers/renderers/display/extensions 已有良好基础。
+
+建议随实际功能修改逐步抽取共享展示对象、API 包装、确认框和状态枚举，合并重复 CSS/词条；不要为了“商业化”一次迁移框架或拆微服务。保留真正使用的旧任务兼容路径，依据路由、调用和测试证据删代码，不能仅凭无导航入口判定整个内部模块无用。
+
+## 已有基础与不应误判之处
+
+- scrypt 使用随机盐、常量时间比较；当前 N=2^14,r=8,p=5 属于 OWASP 列出的可接受配置之一，不应只看 N 就判定哈希不合格。[OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+- Cookie HttpOnly/SameSite Strict、浏览器 CSRF 校验、登录来源检查、账号/IP 限流、令牌哈希和改密撤销会话已有实现；仍应通过 HTTPS 完成传输保护。[会话建议](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
+- 图片 URL 有 HTTPS、允许域名、私网地址及 DNS 连接约束；NAS 凭据传输有证书指纹校验；已有字节/像素限制。依赖解析漏洞说明这些措施仍需分层补强，而非这些措施全部无效。
+- 真实设备写保护、幂等和操作结果未知状态、引用删除保护、生成快照以及当前显示状态核对值得保留。
+- 单用户、单实例和 SQLite 与当前产品定位匹配；不需要为了审计引入租户、计费、角色矩阵或分布式架构。
+- MIT、NOTICE、字体和 Swagger 等第三方声明已存在，不能写成“项目没有许可证”。
+
+## 建议整改顺序与验收
+
+1. 安全基线：A01 依赖与图片插件入口、A02 HTTPS；完善基于可达性的告警处置。
+2. 核心业务：A03 上传找回与生成闭环、A04 原子性/补偿、A06 权限目录一致性。
+3. 产品统一：A10 当前引用/快照契约、A13–A16 导航、目标设备、术语、分页语义；统一覆盖页面与任务。
+4. 交付完善：A07–A09 认证资源和会话、A11–A12 迁移及容量、A17–A19 可访问性和运维隐私；确认启用外部服务商业条款。
+
+最低商业交付验收：新用户能完成连接来源至终端使用全过程；改名/改参数/解绑/删除无引用错乱；图片失败和满盘不产生不可解释状态；HTTPS 会话与最小权限 API 可用；供应商失败、未知写结果和恢复责任有明确界面与说明。
+
+## 本次验证及限制
+
+- 代码审读覆盖认证/授权、请求中间件、存储、图库/方案、图片处理、NAS 分页、主要 UI、部署及许可证声明。
+- 隔离 Mock 复现权限目录缺陷；Playwright 检查 4 页面×2 尺寸并查看实际截图，未修改生产配置。
+- 执行全量 pytest 与依赖扫描，结果见文末验证记录。没有运行恶意图片、生产压测、外网渗透、硬件显示验收或商业法律审查。
+- 本报告为基于当前代码与抽查的工程审计，不是穷尽证明、安全认证或所有页面及业务组合的完整覆盖。
+
+验证记录：pytest **665 passed（124.93s）**；依赖扫描 **37 条告警/3 个锁定包，未通过**；Mock 权限测试返回 **201/400**；8 个页面尺寸组合未发现横向溢出；线上 `/ready` 返回 ready，4 项检查为 true；`git diff --check` 通过。测试通过不抵消安全扫描失败。仅提交本审计文档，无业务修复、依赖升级、部署或正式发布。