← 返回学习路线

SYSTEM

桌面智能创作助手(码字工具)|生产规范

QuillAgent文档
src/content/notes/projects/03-生产规范.md

桌面智能创作助手(码字工具)|生产规范

文档版本:v2.0(重定位·激进瘦身)

包含:开发编码规范、安全规范、配置规范、日志规范、测试规范、构建&部署规范、运维与故障排查、版本发布规范、MVP 已知限制、安全检查清单。 🔵v2.0 变更:产品重定位为码字工具 + AI 赋能;移除多 Agent FSM、写文件人工审批、本地文档 RAG、多会话隔离、Redis 快照、pgvector;数据层由六表收敛为 SQLite 四表(document / doc_version / prompt_template / material,单文件嵌入式、无需独立数据库服务),不再使用 Redis;SSE 事件白名单收敛为 token / error / complete 三种。 本项目 v1.0 定位:单机本地个人使用产品,不面向公网直接暴露服务;无鉴权,禁止把 8080 端口暴露公网,否则外部可任意读写本机数据、盗用第三方 API 产生账单。

1 开发编码规范

1.1 包结构分层规范

com.xxx.writer
├── config              # Spring 配置类;日志脱敏、配置加载/重载、Web/CORS、X-Local-Token 与 Host 校验
├── controller          # REST/SSE 控制器;只做参数校验、请求转发,不写业务逻辑
├── dto                 # 请求/响应 DTO;SSE 事件 DTO;健康接口 DTO
├── exception           # 全局异常、自定义业务异常;错误码翻译,禁止抛原始异常给前端
├── service
│   ├── ai              # AI 赋能服务:续写 continue / 快捷处理 quick / 大纲 outline / 灵感 inspire 编排与 SSE 输出
│   ├── check           # 全文自检:规则引擎(词级,纯函数)+ LLM 语义检查合并
│   ├── modelrouter     # ModelRouter:LOCAL(Ollama) / USER_PROVIDED_API 双模式路由与代理转发
│   ├── document        # 文档 CRUD、版本 diff/回滚、导出(md/txt/word)
│   ├── template        # 文体模板 / prompt_template 服务
│   ├── material        # 素材收藏服务
│   └── search          # 联网素材 SearchProvider 抽象(可选,未配置时置灰)
├── persistence         # MyBatis-Plus:document / doc_version / prompt_template / material 四表映射与 Mapper
├── util                # 通用工具:SSE、字数统计、序列化;禁止放业务逻辑
└── configload          # agent.yml 提示词与参数的启动加载 + 手动重载

分层原则:

  1. Controller 层:只做入参校验、调用 Service、组装返回;禁止复杂业务逻辑,禁止直接操作数据库/文件系统。
  2. Service‑ai / check / document:每个 Service 职责单一、互不耦合;AI 调用一律经 ModelRouter,禁止在业务 Service 内直接 new HTTP 客户端调模型。
  3. ModelRouter:唯一大模型出入口;统一适配 LOCAL / USER_PROVIDED_API;负责 SSE 流式透传与异常翻译。
  4. DTO 设计原则:响应 DTO 严禁回显 apiKey;入参 modelConfig.apiKey 仅请求级传递,不进入任何持久化对象。
  5. util:无状态;禁止持有业务上下文。

1.2 AI 赋能服务编码约束

  1. 续写 / 快捷处理 / 大纲 / 灵感均为单轮短链调用(Controller → Service → ModelRouter),严禁引入任何多节点编排或状态机。
  2. 所有提示词按 genre 从 agent.yml 加载,禁止把提示词硬编码进 Java;字数/风格约束拼入提示词。
  3. AI 生成内容只作为”建议文本”返回前端,不自动落库、不自动覆盖正文;是否采纳 / 替换 / 撤销由前端决定并可撤销。
  4. 续写时上文超长需截取合理长度(如最近 N 字符)再拼提示词,避免超出上下文窗口。
  5. /api/ai/check 的规则引擎必须幂等、纯函数、无外部 IO;LLM 语义结果必须做 JSON 解析容错(返回非法 JSON 时丢弃语义级结果,仅返回规则引擎结果,不报错)。
  6. 素材 content、模板 prompt、版本 content 入库前做长度与格式校验;素材/模板内容不得作为指令解析执行(防 prompt 注入)。

1.3 模型路由 ModelRouter 编码约束

  1. 区分 LOCAL / USER_PROVIDED_API 两种模式;用户 apiKey 只从 POST 请求体 modelConfig 读取,不从 Header 读取。
  2. apiKey 在方法内为局部临时变量;绝对不赋值给任何成员变量、不存入 POJO、不缓存、不落库;请求方法执行结束即释放。
  3. 调用第三方 OpenAI 兼容 API 时后端做 SSE 流式透传;透传过程禁止缓存完整第三方返回大报文,流式逐块转发。
  4. LOCAL 模式下,modelConfig 内 apiKey/baseUrl/modelName 全部直接忽略,不得有任何逻辑去读取使用。
  5. Ollama 调用异常做友好业务异常翻译;区分服务连不上 / 模型不存在 / 显存内存不足,映射为对应业务错误码,不把 Ollama 原始异常堆栈抛前端。
  6. 【单次生成字数】由前端换算后经提示词约束 + maxTokens 双重控制;temperature/maxTokens 由后端透传。

1.4 SSE 流式编码规范(含异常与资源释放)

  1. SSE 输出严格使用白名单事件:token / error / complete;禁止输出白名单之外的事件类型。
  2. SSE 每个 data 块内部是 JSON;严格遵循 SSE 协议 data: {json}\n\n;不要拼接错误换行。
  3. 后端统一用 SseEmitter(spring-boot-starter-web,不引入 WebFlux)承载;订阅 Spring AI 返回的 Flux 时持有 Disposable,客户端断开或取消时主动 dispose() 终止对 Ollama / 第三方的调用,不能只依赖 TCP 断开。
  4. 心跳保活 + 断连检测:约每 15s 发送一次 SSE 心跳包;心跳写入失败即判定客户端已断开 → 立即 dispose() 释放资源,避免模型在后台空跑、线程与网络资源泄漏。
  5. 超时与异常:WebClient 显式设置连接、读取超时;第三方网关 RST / Broken pipe 等异常优雅捕获,不再向已断开的流写数据,转日志记录。
  6. 前端禁止使用 EventSource;全部采用 fetch + ReadableStream,并用 AbortController.abort() 取消请求;代码评审禁止出现 new EventSource。
  7. (可选增强)为每次生成分配 requestId 并维护活跃流集合,提供独立 cancel 接口;v1.0 最低要求是”客户端断开 → dispose 即释放”。

1.5 配置加载规范(热加载已降级)

v2.0 决策:砍掉文件监听(WatchService)与读写锁,规避并发复杂度与文件句柄问题。配置改为启动加载 + 设置页手动重载。

  1. 启动时从数据目录读取 agent.yml;解析异常/格式错误时回滚使用内置默认配置,服务不崩溃。
  2. 设置页提供「重载配置」按钮,触发一次 POST /api/system/reload-config;先解析新配置,成功才整体替换运行配置,失败丢弃并回滚旧配置。
  3. 全部 AI 提示词、检规词库、默认参数外部化到 agent.yml;禁止硬编码进 Java。
  4. 配置变更日志输出 INFO:记录变更来源与结果;禁止打印配置内部敏感字段。

1.6 DTO 与序列化编码规范

  1. 请求 DTO 所有字段开启 validation 参数校验;controller 入参 @Valid。
  2. 禁止直接打印包含 modelConfig 的入参 DTO 对象日志(会误打印密钥);全局日志脱敏过滤器作为最后一道防线,业务代码也要主动规避。
  3. 响应 DTO 严禁回显 apiKey;异常响应只返回错误码 + 友好 message。

1.7 数据层编码规范(SQLite 四表,无 Redis)

  1. SQLite(MyBatis‑Plus,DbType.SQLITE) 四张表,索引与字段约定:
表 用途 关键字段 / 索引
document 文档 id、title、genre、content、char_count、created_at、updated_at
doc_version 历史版本 document_id(外键索引)、content_hash(SHA‑256 唯一索引)、content、char_count、created_at
prompt_template 文体/自定义模板 id、name、prompt、genre(普通索引)、category、is_system、created_at
material 素材 id、genre(普通索引)、kind、content、source、created_at、updated_at
  1. 连接规范:库文件位于应用数据目录(由 --writer.data-dir 解析所得,兜底 ${user.home}/.writer/)下的 writer.db(见 §6.7);driver org.sqlite.JDBC(依赖 org.xerial:sqlite-jdbc);Hikari maximum-pool-size: 1(SQLite 单写,多连接极易 database locked);connection-init-sql 执行 PRAGMA:journal_mode=WAL、synchronous=NORMAL、busy_timeout=5000、foreign_keys=ON。
  2. DDL 方言:主键用 INTEGER PRIMARY KEY AUTOINCREMENT;时间字段用 TEXT 存 ISO8601;不使用 MySQL 的 DATETIME / ENGINE=InnoDB / CHARSET;实体主键 @TableId(type = IdType.AUTO)。
  3. 时间字段 created_at/updated_at 由统一审计填充;禁止在循环内逐条查询(N+1)。
  4. doc_version 按 content_hash 去重(内容未变不落新版本);回滚保留历史不可覆写,回滚作为新版本追加;自动存版由前端在文档切离/退出时调用一次(防高频)。
  5. material 只存纯文本 content,禁止使用素材内容拼装指令;入库做长度/格式校验。
  6. 删除文档使用事务级联删除 doc_version;外键约束依赖连接级 PRAGMA foreign_keys=ON,务必在连接初始化中开启。
  7. 敏感数据入库红线:apiKey 永远不入 SQLite;库文件路径由 application-*.yml 配置;库文件禁止提交 Git(写入 gitignore)。
  8. v1.0 不使用 Redis:无上下文缓存、无全局配额计数、无快照;单机单用户不需要多会话隔离。
  9. v1.1 素材库检索可直接使用 SQLite FTS5 全文索引(替代向量库),无需引入额外组件。
  10. 事务红线:任何数据库事务内禁止包裹网络 IO / AI 调用 / 大模型流式生成;事务内只做纯 DB 操作并快速 commit;禁止长事务、长读事务(长读会阻塞 WAL checkpoint)。
  11. WAL 防膨胀:启动时与定时(应用空闲 / 每 N 分钟)执行 PRAGMA wal_checkpoint(TRUNCATE),避免读事务长期不关闭导致 -wal 文件暴涨占用磁盘。
  12. 单进程独占:v1.0 仅允许后端单进程打开该 db 文件,不支持多进程同时打开同一库(含重复启动后端);Electron 启动前检测并回收残留 8080 进程(见 §6.7)。

1.8 联网素材编码规范(可选增强)

  1. 第三方搜索 key(searchConfig)与 apiKey 同等对待:仅前端 localStorage 保存、请求体内单次传递、禁止落库落日志。
  2. 搜索统一抽象 SearchProvider 接口;v1.0 至少实现一个即可;未配置时 useOnlineSearch=true 返回 ERR-SEARCH-001。
  3. 搜索失败不阻塞主流程:返回搜索失败提示,AI 生成可降级为仅使用本地上下文。

1.9 前端编辑器(TipTap)编码规范

  1. 正文编辑统一使用 TipTap(基于 ProseMirror 的富文本编辑器内核),禁止自研 contenteditable 编辑层。
  2. 内容格式:正文以 HTML(editor.getHTML()) 入库;AI 入参、字数统计、全文自检一律使用纯文本投影(editor.getText());material.content 仍为纯文本。
  3. 自检 offset 基准:/api/ai/check 返回的 offset 以纯文本投影为准(UTF‑16 code unit);前端负责”纯文本 offset ↔ ProseMirror position”映射,替换后重取文本重建映射,禁止用 HTML 字符串下标直接定位。
  4. 版本 diff 基于纯文本投影(避免 HTML 标签噪声);存版快照仍存 HTML,content_hash 对存储快照计算。
  5. 续写 / quick 的插入与原地替换必须通过 TipTap 事务(transaction / dispatch) 执行,确保进入撤销栈,满足”可撤销 / 可回退”。
  6. IME:TipTap/ProseMirror 已内部处理 Composition 事件;字数统计基于 getText(),避免输入法推荐词虚增计数。
  7. 编辑器相关依赖(@tiptap/vue-3 及所需扩展)版本锁定,禁止跨大版本随意升级。

2 安全规范(最高优先级,红线)

本项目 v1.0 是本地单机产品:严禁将后端 8080 端口直接暴露公网;没有鉴权,暴露公网将允许外部任意人读取文档数据、盗用你的第三方 API 额度。

2.1 用户 API‑Key 安全规范(红线)

  1. ✅唯一来源:HTTP POST 请求体 modelConfig.apiKey;局部临时变量。
  2. ✅生命周期:仅单次 HTTP 请求方法内存;请求处理完成即释放。
  3. ❌禁止:存入成员变量、全局变量、缓存、数据库、yml 配置文件。
  4. ❌禁止:打印到任何日志(info/debug/trace);禁止异常堆栈打印;禁止返回报文回显。
  5. ✅防护手段:
    • 日志层脱敏(v2.0 降级方案):不包装/篡改请求体(包装请求体会破坏 SSE 流式与框架行为),改为对送往日志的字符串统一正则脱敏(apiKey 值、sk-*、tvly-* 等替换为 ***),作为最后一道防线。
    • 代码评审:每一处日志打印、DTO/POJO 字段严格检查;禁止打印包含 modelConfig 的入参 DTO 对象。
    • Electron 主进程与渲染进程禁止 console 打印 apiKey;前端代码评审所有 console 语句。

2.2 输入与提示注入安全

  1. SSE 事件严格白名单;不把模型原始输出直接作为后端指令执行。
  2. 素材 / 模板 / 版本 content 入库前校验长度与格式,且不作为指令解析执行。
  3. 全文自检 LLM 返回结果解析容错,不执行 LLM 返回内容中的任何”指令”。

2.3 Electron 桌面壳安全规范

  1. 渲染进程:contextIsolation: true、nodeIntegration: false、sandbox: true;仅通过 preload 暴露白名单能力(文件选择、保存、窗口控制、注入 token)。
  2. 不加载远程网页内容;内容安全策略 CSP 收紧到仅 localhost:8080。
  3. 主进程与渲染进程禁止 console 打印密钥;配置存储仅 localStorage;主进程不持久化任何 apiKey。
  4. 应用不包含任何硬编码密钥;全部由用户设置页输入。
  5. 本机接口令牌(X‑Local‑Token):主进程读取后端写入数据目录的 token 文件,经 preload 注入渲染进程;渲染进程所有业务请求头携带 X-Local-Token;token 不写入 localStorage、不打印、不经过任何 HTTP 接口传输。

2.4 网络与接口安全红线(纵深防御)

v1.0 为单机可信环境:后端只能本机 127.0.0.1 访问;禁止端口转发、禁止公网暴露 8080 端口。 说明:v1.0 无用户登录体系,但有本机接口令牌 X-Local-Token 作为纵深防御(见 §2.5),仅用于阻断浏览器网页发起的跨页攻击,不等于面向公网的鉴权体系。

  • ❌错误:云服务器直接开放 8080;内网端口映射把 8080 暴露外网;宿主机模式后端绑定 0.0.0.0;CORS 使用 *。
  • ✅正确:两种拓扑下后端均只绑定 127.0.0.1——宿主机模式通过 server.address=127.0.0.1;容器模式通过 docker‑compose 端口映射 127.0.0.1:8080:8080;桌面应用访问 http://localhost:8080。

如未来需要公网部署,必须另建完整登录鉴权体系;该点写入 README 部署警告。

2.5 本机接口令牌(X‑Local‑Token)规范

背景:localhost 不是安全边界——恶意网页可通过 fetch / DNS rebinding 访问本机 127.0.0.1 服务。仅绑定回环地址不足以防跨页攻击,故增加一次性令牌。

  1. 生成与传递闭环:后端启动生成一次性随机 token → 写入应用数据目录下的本地文件 → Electron 主进程读取 → 经 preload 注入渲染进程 → 请求头携带 X-Local-Token;token 绝不通过 HTTP 接口下发、绝不放请求体、绝不落日志/入库。
  2. 校验:所有业务接口(健康探测与 GET /api/system/info 除外)强制校验 X-Local-Token,不匹配返回 401 ERR-AUTH-001。
  3. Host 校验:仅允许 localhost / 127.0.0.1,拒绝其他 Host(防 DNS rebinding)。
  4. CORS:禁用 *,仅精确匹配生产 file://(Origin: null)与开发 http://localhost:5173。
  5. 威胁模型声明:v1.0 仅防御”浏览器网页发起的跨页攻击”,不防御本机已存在的恶意程序(其可读取本地文件、拿到 token);该边界写入论文 / README。

3 配置规范

3.1 配置文件拆分

  1. application.yml:基础服务配置、日志级别、线程池、Ollama 地址(ollama.base-url)、SQLite 连接配置(库文件路径取自数据目录,PRAGMA 见 §1.7;不存放任何用户第三方 API‑Key)。
  2. config/agent.yml:三套文体系统提示词(NOVEL/MEDIA/OFFICIAL)、续写/quick/outline/inspire 提示词模板、自检词库与格式正则、默认生成参数;启动加载 + 设置页手动重载(不做文件监听热加载,见 §1.5)。
  3. docker-compose.yml:容器编排(backend / ollama 两容器,无数据库容器);仅用于开发调试与本地部署验证,不作为桌面交付方案;区分生产 docker-compose.yml 与开发 docker-compose.dev.yml。

3.2 配置外部化原则

  1. 硬编码魔法值全部抽配置;例如单次生成默认 token、SSE 超时、默认模型名、字数换算系数。
  2. 提示词不写死 Java 代码,全部外部化到 agent.yml;启动加载 + 设置页手动重载(不做文件监听热加载)。
  3. 开发/生产配置分离;生产环境关闭 debug 日志。

3.3 敏感配置

v1.0 后端不接收、不存储用户第三方 API‑Key,因此后端配置文件不需要存放第三方密钥。 Ollama 地址由 ollama.base-url 配置:宿主机模式默认 127.0.0.1:11434;容器模式配置为 http://ollama:11434(容器服务名,勿用 127.0.0.1)。v1.0 不支持配置局域网远端 Ollama 地址(v1.1 迭代支持)。 联网搜索 key 仅存前端 localStorage,后端配置文件不保存。

4 日志规范

4.1 日志级别划分

  • production 生产环境:root=INFO;Spring 框架日志 INFO;业务日志 INFO;关闭 DEBUG/TRACE。
  • development 开发环境:root=DEBUG;方便调试。

Docker Compose 生产 profile 强制设置日志级别 INFO。

4.2 日志字段规范

业务日志尽量包含:requestId、documentId(AI 调用另含 genre、mode);便于追踪。

requestId 通过 MDC 链路追踪生成。

4.3 禁止输出内容(强制)

  1. ❌禁止输出用户 API‑Key(含联网搜索 key);全局过滤器脱敏;业务代码也不得打印 modelConfig 完整对象。
  2. ❌禁止打印完整原始用户大报文(长正文可截断打印)。
  3. ❌禁止把第三方模型原始异常堆栈直接输出给前端;后端日志可记录完整异常,前端只展示业务 message + 错误码。

4.4 必须记录的审计日志(INFO 级别)

  1. 文档新建 / 删除 / 导出。
  2. AI 调用:记录 documentId、genre、mode(LOCAL/USER_PROVIDED_API)、耗时;不打印 apiKey。
  3. 全文自检执行:genre、问题数量。
  4. 版本存版 / 回滚:documentId、versionId。
  5. 配置加载 / 手动重载成功或失败;来源与结果。
  6. 模型模式切换事件:LOCAL / USER_PROVIDED_API;不打印 apiKey。

4.5 日志脱敏实现说明

在日志输出层做统一脱敏(如自定义 MessageConverter / Layout,或对日志字符串做正则替换):检测 apiKey 值、sk-*、tvly-* 等特征串,替换为 ***;不包装/篡改请求体(避免破坏 SSE 流式与框架行为)。

脱敏是最后一道防线;业务代码不能依赖它而放松编码约束。

5 测试规范

5.1 单元测试(收敛为 5 个关键用例)

原则:v1.0 只覆盖”改错会出红线事故”的核心路径,不追求覆盖率数字;需要 Spring 上下文的用例用 @SpringBootTest。

必测 5 个关键用例:

  1. ModelRouter 分支:LOCAL 模式忽略 apiKey;USER_PROVIDED_API 参数解析;异常翻译为业务错误码。
  2. 日志脱敏:含 apiKey 的日志行输出后确认被替换为 ***。
  3. 自检规则引擎:各 genre 检规命中(重复用词 / 敏感词 / 口语化 / 格式),且幂等、纯函数、无 IO。
  4. 文档版本:content_hash 去重、回滚作为新版本追加。
  5. offset 映射函数:纯文本 offset ↔ ProseMirror pos 转换,覆盖换行与中英混排。

其余项(导出正确性、DTO 参数校验、配置重载回滚、字数统计等)以集成测试 / 手工回归覆盖,不单列单测,避免挤占工期。

5.2 集成测试(SpringBootTest + MockMvc)

  1. SSE 流式集成:续写 / quick / outline / inspire 返回 token + complete,无白名单外事件。
  2. /api/ai/check 混合自检返回结构(词级 + 语义级合并、summary)集成测试。
  3. 文档 CRUD + 版本(存版/对比/回滚)+ 导出集成测试。
  4. 健康探测接口集成测试;模拟 Ollama 可用/不可用/模型缺失场景。
  5. 模板 / 素材 CRUD 集成测试(genre 过滤、长度校验)。

5.3 安全专项测试(交付前必须手工执行)

安全测试用例文档留存仓库 docs/security-test-cases.md。

  1. 密钥泄露专项测试:
    • 检查应用日志,确认无明文 apiKey;
    • 检查异常堆栈输出,确认不打印 apiKey;
    • Electron 渲染进程开发者工具控制台,确认不打印 apiKey(含 search key)。
  2. 提示注入测试:素材/模板内容包含指令语句时不被后端执行。
  3. 异常场景测试:
    • Ollama 关闭,本地模式返回友好提示;
    • 用户传入错误 apiKey,返回业务错误码,不抛堆栈;
    • 配置文件损坏,热加载回滚旧配置,服务不崩溃。

5.4 端到端联调测试(前后端完整链路)

  1. 场景 1(自有 API 模式):设置页填密钥→写作→续写→快捷处理→导出,全链路。
  2. 场景 2(本地 Ollama 模式):健康检测 READY→续写→全文自检→导出。
  3. 场景 3:Ollama 不可达(UNAVAILABLE)/ 模型缺失(MODEL_MISSING)→ 本地模式单选置灰 → UI 引导与 FAQ。
  4. 场景 4:SSE 断连重连;网络异常友好降级。
  5. 场景 5:崩溃/重启恢复草稿;存版/对比/回滚;导出。
  6. 场景 6(AI 赋能全景):文体切换→模板生效→大纲生成跳转→素材收藏插入→划选 quick 四操作→全文自检标红替换→暗色/悬浮字数→参数双预设切换。
  7. 场景 7(桌面进程编排,R1):冷启动显示遮罩直至后端就绪;关闭应用后无残留 java 进程、8080 端口已释放;运行中强制 kill 后端 → UI 提示并自动重启;二次启动不报端口冲突。

5.5 测试禁止

  1. 单元/集成测试用例不要写入真实有效的第三方 apiKey;全部使用 mock。
  2. 不要提交包含真实密钥的配置文件到 Git 仓库;gitignore 屏蔽本地 yml。

6 构建与部署规范

6.1 Git 版本管理规范

  1. main 为主分支;开发分支 develop;每个里程碑完成打 Git Tag:v0.1 ~ v1.0。
  2. commit 规范:feat / fix / refactor / test / docs / security。
  3. gitignore 配置:忽略本地 application-local.yml、日志目录、docker 环境文件、前端 node_modules。
  4. 严禁把任何真实密钥提交 Git 仓库。

6.2 Maven 构建规范

  1. maven profile 区分 dev / prod。
  2. prod 打包:关闭 dev 调试端点;日志级别 INFO;剔除测试类;构建可执行 jar。
  3. 构建产物:后端 jar;Electron 前端打包产物(安装包 + zip);不要把大模型文件打进镜像;Ollama 模型由用户 pull。

6.3 部署规范:开发/调试拓扑(非桌面交付方案)

⚠️以下两种拓扑仅用于开发调试与本地部署验证;面向普通用户的正式交付形态是”Electron 桌面安装包”(内含 jlink 裁剪 JRE + 后端 jar),不要求用户安装 Docker / JDK(见 §6.5 / §6.7)。

拓扑 A 宿主机模式(推荐开发调试)

  • 后端 jar 在宿主机直接运行;Ollama 在宿主机安装;ollama.base-url=127.0.0.1:11434;
  • 后端通过 server.address=127.0.0.1 只绑定本机回环,禁止 0.0.0.0;
  • 健康探测收敛为 3 状态(UNAVAILABLE / MODEL_MISSING / READY),宿主机与容器模式一致。

拓扑 B Docker Compose 容器模式(可选,本地自托管)

  • backend / ollama 两个容器全部运行本机;ollama.base-url=http://ollama:11434(容器服务名,不能用 127.0.0.1);
  • 数据层为 SQLite 单文件,随 backend 挂载卷持久化(如 ./data/writer.db);不再需要 MySQL 容器与数据库数据卷;
  • backend 容器内无法探测宿主机 Ollama 安装状态,“未安装/未启动”合并为”无法连接”引导文案;
  • 端口仅绑定 127.0.0.1,不要绑定 0.0.0.0,防止意外对外暴露。

docker‑compose.yml 关键配置约束示例:

services:
  backend:
    build: ./backend
    ports:
      - "127.0.0.1:8080:8080" # 重要!绑定回环,不对外网暴露
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434 # 容器模式使用服务名,勿用127.0.0.1
      - SPRING_DATASOURCE_URL=jdbc:sqlite:/app/data/writer.db
    volumes:
      - ./config:/app/config   # 热加载配置
      - ./data:/app/data       # SQLite 库文件(writer.db)持久化
    depends_on:
      - ollama
  ollama:
    image: ollama/ollama
    ports:
      - "127.0.0.1:11434:11434"
    volumes:
      - ollama-models:/root/.ollama # 模型数据卷持久化
volumes:
  ollama-models:

文档重点警告:不要修改为 0.0.0.0;不要云服务器直接部署该 v1.0 版本对外提供服务;无鉴权会造成严重安全风险。

部署步骤文档:

  1. 执行 docker compose up -d(首次启动自动初始化 SQLite 表结构:Flyway/SQL 脚本执行建表,库文件生成于挂载的 ./data/writer.db);
  2. Ollama 容器需要手动执行 ollama pull qwen2.5:3b 下载对话模型;镜像不会内置大模型;文档写清楚;
  3. 启动成功后桌面应用设置页后端地址填写 http://localhost:8080;
  4. 打开应用健康检测,确认本地模型就绪(或直接在设置页填入自有 API 密钥);
  5. 两种使用路径说明:自有 API 开箱即用 / 本地 Ollama 模式需要 pull 预训练模型,不需要训练模型。

6.4 容器镜像优化

  1. backend 镜像采用 jre21 精简基础镜像;不要完整 JDK。
  2. 分层构建;maven 依赖层缓存,加速构建。
  3. Ollama 镜像使用官方 ollama 镜像;模型数据卷持久化;不要把模型打进镜像层。

6.5 Electron 桌面端打包规范

  1. 前端工程:Vite + Vue3 构建 dist → 由 electron‑builder 打包为 Windows NSIS 安装程序(.exe);同时产出免安装 zip 便于分发。
  2. 渲染进程安全基线:contextIsolation、sandbox 开启,nodeIntegration 关闭;打包产物启用 ASAR。
  3. 应用不内置 Ollama 与模型;首次使用引导用户安装 Ollama / 或直接填自有 API 密钥。
  4. 打包产物命名带版本号(Writer-Assistant-Setup-1.0.0.exe);安装后生成桌面快捷方式与开始菜单项。
  5. 后端与 JRE 随包分发:用 jlink 裁剪最小 JRE(约 50‑90MB),与后端 jar 一并放入 electron‑builder 的 extraResources;主进程用该 JRE 启动 jar,不依赖用户电脑预装 JDK21。v1.0 仅编译 Windows x64 一份。
  6. 进程管理依赖:引入 tree-kill(Windows 等价 taskkill /T /F),退出时杀整棵 Java 进程树;主进程用 spawn(java, [...], { shell:false }) 使 java 成为直接子进程,保证 child.kill() 有效。
  7. 打包后路径:所有资源路径用 app.getPath('userData') 动态获取,禁止写死相对路径;数据目录经 --writer.data-dir 传给后端(见 §6.7)。
  8. 打包后冒烟测试(不可省略):安装 → 启动遮罩 → 后端就绪 → 写作/续写 → 导出 → 退出无残留进程;列入交付清单必备项。

6.6 部署交付物清单

  1. 后端可执行 jar;
  2. Windows x64 桌面安装包(NSIS .exe)+ 免安装 zip(内含 jlink 裁剪 JRE 与后端 jar)——正式交付形态;
  3. docker-compose.yml + docker-compose.dev.yml(含 backend/ollama 两容器)——仅开发调试用,非交付主形态;
  4. SQLite 四表建表 SQL / Flyway 迁移脚本;
  5. 样例 agent.yml(含三套文体提示词)、demo 文档;
  6. 全套 Markdown 文档:01 需求 / 02 接口 / 03 生产规范 / 04 工作计划表 / 故障排查清单 / 安全测试用例;
  7. 打包后冒烟测试记录;
  8. 演示录屏。

6.7 桌面交付与进程编排(R1 / R7)

后端 jar 是随桌面应用启动的本地 Java 进程,不是独立服务;其生命周期由 Electron 主进程统一编排,否则会出现”关窗后 Java 残留、8080 被占用、二次启动失败”。

(一)进程编排

  1. 拉起:主进程 spawn(javaFromJlink, ['-jar', backendJar, '--writer.data-dir=<userData>/data'], { shell:false })——不套 shell,java 即直接子进程,child.kill() 有效。
  2. 杀进程树:额外用 tree-kill(Windows 等价 taskkill /T /F)兜底,退出时杀整棵 Java 进程树,避免残留线程占用端口。
  3. 启动遮罩:窗口先渲染遮罩,轮询健康接口(/api/status/local-model 或 /api/system/info)直至就绪;未就绪禁止显示编辑器,失败显示错误与重试。
  4. 崩溃自愈:监听 child.on('exit'/'close'),非主动退出判定为崩溃 → 自动重启 + UI 提示;多次失败提示手动排查。
  5. 残留端口回收:启动前检测 8080,若为上次残留则回收再启动。
  6. 优雅停机:JVM 注册 ShutdownHook;后端暴露 shutdown 端点(仅 127.0.0.1);退出时先调 shutdown 接口,失败再 tree-kill 强杀。

(二)数据目录与路径(R7)

  1. Electron 主进程传 --writer.data-dir=<userData>/data;Java 侧 WriterHome 解析顺序:启动参数 → 环境变量 → user.home 兜底。
  2. 配置 agent.yml、SQLite writer.db、token 文件全部落在该目录;严禁写死相对路径(开发环境跑通、打包后路径全变是典型坑)。
  3. 打包后必须做冒烟测试(见 §6.5-8),不能只靠开发环境联调。

7 运维与故障排查规范(v1.0 单机个人使用)

7.1 v1.0 运维限制说明

v1.0:文档 / 版本 / 模板 / 素材全部存本机 SQLite 单文件(应用数据目录下 writer.db,见 §6.7);重启 backend 后数据仍在;数据即本地文件,备份即复制该文件;无独立数据库服务,不存在”数据库服务未启动”故障面。文档显著位置提示用户定期备份该 .db 文件。

7.2 常见故障排查清单(写入交付 README)

  1. 桌面应用健康检测显示 Ollama 未连接:检查 ollama 容器 / 本地 ollama 是否启动;地址是否与配置项 ollama.base-url 一致(宿主机 127.0.0.1:11434 / 容器 ollama:11434);
  2. 本地模式就绪但续写报错 OOM:内存不足;切换 qwen2.5:1.5b 小模型;
  3. 自有 API 模式报错密钥错误:确认应用设置页 apiKey、baseUrl、modelName 填写正确;用【测试连通性】按钮校验;
  4. 修改 agent.yml 配置不生效:v1.0 无文件监听热加载,需在设置页点【重载配置】或重启应用;配置解析失败会回滚旧配置,查看应用日志 INFO 的加载日志;
  5. backend 重启后文档打不开:检查数据目录下 SQLite 库文件是否被删除或权限不足(桌面模式 <userData>/data/writer.db;开发容器模式挂载的 /app/data/writer.db);
  6. 访问 8080 来自其他机器连接被拒绝:这是预期安全行为,v1.0 只允许本机 localhost 访问;
  7. 全文自检无结果:确认 genre 是否选择(检规按 genre 加载);LLM 语义检查失败时仍应返回规则引擎结果;
  8. 导出 word 乱码/格式异常:确认使用 POI XWPF 生成,字体使用通用字体;v1.0 仅支持基础标题/段落排版,复杂样式请导出后自行处理。
  9. 应用启动一直显示”后端正在启动”:首次 JVM 冷启动较慢(耐心等待)或后端启动失败;查看日志,尝试重启应用;若提示端口被占用,多为上次残留进程,关闭其他实例后重试。
  10. 关闭应用后 java 进程残留 / 8080 被占:属 R1 编排故障;确认主进程已接入 tree-kill 并在退出时先调 shutdown 端点、失败再强杀;临时可手动结束残留进程。
  11. 请求返回 401 ERR-AUTH-001:本机令牌未正确注入;确认主进程已读取数据目录 token 文件并经 preload 注入,且请求头携带 X-Local-Token(健康探测与 /api/system/info 除外)。

7.3 运维日志查看

docker compose logs -f backend

生产日志重点查看:audit 审计日志;错误码 ERR‑*;不要去原始日志搜索 apiKey,过滤器已经脱敏。

7.4 备份策略 v1.0

  1. 后端:配置目录 ./config 手动备份;SQLite 库文件定期备份(直接复制 writer.db,或执行 VACUUM INTO 'backup.db' 生成一致性快照;WAL 模式下建议在无写入时复制,或一并复制 writer.db-wal/writer.db-shm);
  2. 桌面应用:设置页导出 JSON 配置备份(包含用户 apiKey,备份文件妥善保管,不要公开)。

v1.0 没有自动备份功能,全部手动备份;文档写明。

8 版本发布流程规范

8.1 里程碑发布流程(v0.1~v1.0)

  1. 完成阶段全部开发;
  2. 执行全部单元测试 + 集成测试;全部通过;
  3. 执行安全专项测试;安全用例全部通过;
  4. 更新对应文档(需求、接口、生产规范、工作计划表同步版本号);
  5. Git commit 全部变更;打对应 Tag;
  6. 构建 docker 镜像、Electron 打包产物;
  7. 编写本版本变更日志 CHANGELOG.md;
  8. 里程碑验收;记录已知限制、MVP 边界;
  9. 交付归档。

8.2 CHANGELOG.md 规范

每个版本记录:新增功能、修复 bug、安全修复、不兼容变更、MVP 已知限制。

9 MVP 已知限制清单(部署文档显著位置必须展示)

v1.0 明确限制,避免用户产生错误预期;全部写入 README 首页。

  1. 文档 / 版本 / 模板 / 素材全部存本机 SQLite 单文件:数据即本地文件(writer.db),无需安装数据库服务;建议定期复制该文件备份,文件损坏或被误删需从备份还原。
  2. v1.0 没有用户登录鉴权;后端端口只能绑定 127.0.0.1 本机访问;严禁暴露公网;公网使用需要完整鉴权体系(v1.2 SaaS 分支)。
  3. 无法按每个用户传入的第三方 API‑Key 独立统计配额;用户额度请到第三方模型服务商控制台查看。
  4. Electron 桌面应用不自动安装 Ollama、不自动执行终端下载模型;本地模式需要用户手动安装 Ollama 并 pull 预训练模型,不需要训练模型。
  5. AI 能力为单轮短链调用,不提供多 Agent 自动编排、自动写文件流水线;AI 产出需用户确认后手动采纳。
  6. v1.0 仅交付 Windows x64(Windows 10/11),不提供 macOS / Linux 安装包;不做浏览器扩展、不做网页划词。
  7. 卸载应用会丢失 localStorage 中全部配置(含 apiKey、写作参数预设、自动缓存草稿);需要用户提前导出 JSON 备份。
  8. 联网素材为外部依赖项:需用户申请第三方搜索 API 并在设置页填入 key;key 未配置时联网开关置灰,不影响本地模式与其他功能。
  9. 历史版本仅「手动存版 + 会话结束自动存一版」;doc_version 内容上限与素材条数受本机 SQLite 文件与本机磁盘容量限制,超存量建议手动清理。
  10. v1.0 不使用 Redis、不提供本地文档 RAG 知识库、不提供多会话隔离;素材库检索作为 v1.1 可选增强。
  11. word 导出为结构化降级(标题 + 段落),不支持复杂样式 / 图文混排;如需复杂排版请导出后自行处理。
  12. 打字机模式、LLM 语义级自检、联网素材搜索、配置文件监听热加载属 P2,v1.0 不承诺交付(有余力再做)。
  13. 后端以 Java 进程随应用启动,安装包含 jlink 裁剪 JRE,整机约需数百 MB 磁盘;冷启动需数秒,期间显示启动遮罩。
  14. 后端为随应用启动的本地进程,仅支持单进程独占 SQLite 库文件;请勿重复启动应用或手动再起一个后端实例。

10 安全检查清单(发布前逐条勾选)

  • 后端端口仅绑定 127.0.0.1(宿主机模式 server.address=127.0.0.1;容器模式端口映射 127.0.0.1),不是 0.0.0.0;README 有高危警告禁止公网暴露 v1.0。
  • 全局日志脱敏过滤器实现;单元测试校验密钥脱敏生效。
  • ModelRouter 用户 apiKey 仅 POST 请求体传入;不使用 HTTP Header;仅局部临时变量;不存入任何持久化对象。
  • 响应 DTO 与异常报文不回显 apiKey;单元测试覆盖。
  • Electron 渲染进程安全基线:contextIsolation、sandbox 开启,nodeIntegration 关闭;不加载远程网页;CSP 收紧至仅 localhost:8080;仅通过 preload 暴露白名单能力。
  • Electron 主进程与渲染进程前端代码评审,没有 console 打印 apiKey(含搜索服务 search key)。
  • SSE 事件白名单校验;续写/quick/outline/inspire 未输出白名单之外的事件类型;前端无 new EventSource。
  • 异常处理:所有业务异常翻译为友好 message + 错误码;原始 Java 异常堆栈不会返回前端。
  • Git 仓库没有提交任何真实密钥;gitignore 配置正确。
  • README、应用设置页 FAQ 全部文案删除”训练模型”错误表述;反复澄清本地模式下载预训练模型,不需要训练模型。
  • material 素材、prompt_template 模板、doc_version 版本入库校验长度与格式;doc_version 按 content_hash 去重;素材/模板内容不作为指令解析执行。
  • 联网搜索 key(searchConfig)与 apiKey 同等管控:仅 localStorage、仅请求体内存、不落库不落日志。
  • 全文自检 LLM 返回非法 JSON 时优雅降级(仅返回规则引擎结果)。
  • 完整安全专项测试手工执行完成;安全测试用例文档留存。
  • 所有业务接口强制校验 X-Local-Token(健康探测与 /api/system/info 除外),缺失/错误返回 401 ERR-AUTH-001;token 由后端启动写入数据目录本地文件,不经 HTTP 下发、不入日志、不入 localStorage。
  • Host 头校验仅允许 localhost / 127.0.0.1;CORS 禁用 *,仅匹配生产 file://(Origin: null)与开发 http://localhost:5173。
  • Electron 主进程以 shell:false 直接 spawn jlink JRE 启动后端;退出时先调 shutdown 端点、失败则 tree-kill 杀进程树;启动前回收残留 8080。
  • 启动遮罩生效:后端未就绪不显示编辑器;后端崩溃自动重启并提示;二次启动无端口冲突。
  • 打包后冒烟测试已执行:安装 → 启动 → 写作/续写 → 导出 → 退出无残留进程、端口已释放。
  • 数据目录经 --writer.data-dir 注入,配置/库文件/token 均落该目录;无硬编码相对路径。

11 附录:依赖与版本

  • 后端:JDK21、Spring Boot 3.5.x、Spring AI 1.x GA(Spring AI 2.0 GA 基于 Spring Boot 4,与本项目不兼容,锁定 1.x);SSE 用 spring-boot-starter-web 的 SseEmitter,不引入 WebFlux。
  • 数据层:SQLite(org.xerial:sqlite-jdbc,MyBatis‑Plus 指定 DbType.SQLITE);v2.0 不再使用 Redis。
  • 前端/桌面:Electron ≥28、Vite + Vue3 + Element Plus + TipTap(ProseMirror 内核);electron-builder 打包;tree-kill 管理 Java 进程树;jlink 裁剪 JRE 随包;v1.0 仅 Windows x64。
  • 模型接入:Ollama 原生 HTTP 接口(本地模式);第三方模型 OpenAI 兼容 REST 协议(自有 API 模式)。
  • 文档导出:Apache POI(XWPF)生成 .docx(结构化降级)。