SYSTEM
桌面智能创作助手(码字工具)|生产规范
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 提示词与参数的启动加载 + 手动重载
分层原则:
- Controller 层:只做入参校验、调用 Service、组装返回;禁止复杂业务逻辑,禁止直接操作数据库/文件系统。
- Service‑ai / check / document:每个 Service 职责单一、互不耦合;AI 调用一律经 ModelRouter,禁止在业务 Service 内直接 new HTTP 客户端调模型。
- ModelRouter:唯一大模型出入口;统一适配 LOCAL / USER_PROVIDED_API;负责 SSE 流式透传与异常翻译。
- DTO 设计原则:响应 DTO 严禁回显 apiKey;入参
modelConfig.apiKey仅请求级传递,不进入任何持久化对象。 - util:无状态;禁止持有业务上下文。
1.2 AI 赋能服务编码约束
- 续写 / 快捷处理 / 大纲 / 灵感均为单轮短链调用(Controller → Service → ModelRouter),严禁引入任何多节点编排或状态机。
- 所有提示词按
genre从agent.yml加载,禁止把提示词硬编码进 Java;字数/风格约束拼入提示词。 - AI 生成内容只作为”建议文本”返回前端,不自动落库、不自动覆盖正文;是否采纳 / 替换 / 撤销由前端决定并可撤销。
- 续写时上文超长需截取合理长度(如最近 N 字符)再拼提示词,避免超出上下文窗口。
/api/ai/check的规则引擎必须幂等、纯函数、无外部 IO;LLM 语义结果必须做 JSON 解析容错(返回非法 JSON 时丢弃语义级结果,仅返回规则引擎结果,不报错)。- 素材 content、模板 prompt、版本 content 入库前做长度与格式校验;素材/模板内容不得作为指令解析执行(防 prompt 注入)。
1.3 模型路由 ModelRouter 编码约束
- 区分 LOCAL / USER_PROVIDED_API 两种模式;用户 apiKey 只从 POST 请求体 modelConfig 读取,不从 Header 读取。
- apiKey 在方法内为局部临时变量;绝对不赋值给任何成员变量、不存入 POJO、不缓存、不落库;请求方法执行结束即释放。
- 调用第三方 OpenAI 兼容 API 时后端做 SSE 流式透传;透传过程禁止缓存完整第三方返回大报文,流式逐块转发。
- LOCAL 模式下,modelConfig 内 apiKey/baseUrl/modelName 全部直接忽略,不得有任何逻辑去读取使用。
- Ollama 调用异常做友好业务异常翻译;区分服务连不上 / 模型不存在 / 显存内存不足,映射为对应业务错误码,不把 Ollama 原始异常堆栈抛前端。
- 【单次生成字数】由前端换算后经提示词约束 + maxTokens 双重控制;temperature/maxTokens 由后端透传。
1.4 SSE 流式编码规范(含异常与资源释放)
- SSE 输出严格使用白名单事件:token / error / complete;禁止输出白名单之外的事件类型。
- SSE 每个 data 块内部是 JSON;严格遵循 SSE 协议
data: {json}\n\n;不要拼接错误换行。 - 后端统一用
SseEmitter(spring-boot-starter-web,不引入 WebFlux)承载;订阅 Spring AI 返回的Flux时持有Disposable,客户端断开或取消时主动dispose()终止对 Ollama / 第三方的调用,不能只依赖 TCP 断开。 - 心跳保活 + 断连检测:约每 15s 发送一次 SSE 心跳包;心跳写入失败即判定客户端已断开 → 立即
dispose()释放资源,避免模型在后台空跑、线程与网络资源泄漏。 - 超时与异常:WebClient 显式设置连接、读取超时;第三方网关 RST / Broken pipe 等异常优雅捕获,不再向已断开的流写数据,转日志记录。
- 前端禁止使用 EventSource;全部采用 fetch + ReadableStream,并用
AbortController.abort()取消请求;代码评审禁止出现new EventSource。 - (可选增强)为每次生成分配
requestId并维护活跃流集合,提供独立 cancel 接口;v1.0 最低要求是”客户端断开 → dispose 即释放”。
1.5 配置加载规范(热加载已降级)
v2.0 决策:砍掉文件监听(WatchService)与读写锁,规避并发复杂度与文件句柄问题。配置改为启动加载 + 设置页手动重载。
- 启动时从数据目录读取
agent.yml;解析异常/格式错误时回滚使用内置默认配置,服务不崩溃。 - 设置页提供「重载配置」按钮,触发一次
POST /api/system/reload-config;先解析新配置,成功才整体替换运行配置,失败丢弃并回滚旧配置。 - 全部 AI 提示词、检规词库、默认参数外部化到
agent.yml;禁止硬编码进 Java。 - 配置变更日志输出 INFO:记录变更来源与结果;禁止打印配置内部敏感字段。
1.6 DTO 与序列化编码规范
- 请求 DTO 所有字段开启 validation 参数校验;controller 入参
@Valid。 - 禁止直接打印包含 modelConfig 的入参 DTO 对象日志(会误打印密钥);全局日志脱敏过滤器作为最后一道防线,业务代码也要主动规避。
- 响应 DTO 严禁回显 apiKey;异常响应只返回错误码 + 友好 message。
1.7 数据层编码规范(SQLite 四表,无 Redis)
- 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 |
- 连接规范:库文件位于应用数据目录(由
--writer.data-dir解析所得,兜底${user.home}/.writer/)下的writer.db(见 §6.7);driverorg.sqlite.JDBC(依赖org.xerial:sqlite-jdbc);Hikarimaximum-pool-size: 1(SQLite 单写,多连接极易database locked);connection-init-sql执行 PRAGMA:journal_mode=WAL、synchronous=NORMAL、busy_timeout=5000、foreign_keys=ON。 - DDL 方言:主键用
INTEGER PRIMARY KEY AUTOINCREMENT;时间字段用TEXT存 ISO8601;不使用 MySQL 的 DATETIME / ENGINE=InnoDB / CHARSET;实体主键@TableId(type = IdType.AUTO)。 - 时间字段
created_at/updated_at由统一审计填充;禁止在循环内逐条查询(N+1)。 doc_version按content_hash去重(内容未变不落新版本);回滚保留历史不可覆写,回滚作为新版本追加;自动存版由前端在文档切离/退出时调用一次(防高频)。material只存纯文本 content,禁止使用素材内容拼装指令;入库做长度/格式校验。- 删除文档使用事务级联删除 doc_version;外键约束依赖连接级
PRAGMA foreign_keys=ON,务必在连接初始化中开启。 - 敏感数据入库红线:apiKey 永远不入 SQLite;库文件路径由
application-*.yml配置;库文件禁止提交 Git(写入 gitignore)。 - v1.0 不使用 Redis:无上下文缓存、无全局配额计数、无快照;单机单用户不需要多会话隔离。
- v1.1 素材库检索可直接使用 SQLite FTS5 全文索引(替代向量库),无需引入额外组件。
- 事务红线:任何数据库事务内禁止包裹网络 IO / AI 调用 / 大模型流式生成;事务内只做纯 DB 操作并快速 commit;禁止长事务、长读事务(长读会阻塞 WAL checkpoint)。
- WAL 防膨胀:启动时与定时(应用空闲 / 每 N 分钟)执行
PRAGMA wal_checkpoint(TRUNCATE),避免读事务长期不关闭导致-wal文件暴涨占用磁盘。 - 单进程独占:v1.0 仅允许后端单进程打开该 db 文件,不支持多进程同时打开同一库(含重复启动后端);Electron 启动前检测并回收残留 8080 进程(见 §6.7)。
1.8 联网素材编码规范(可选增强)
- 第三方搜索 key(
searchConfig)与 apiKey 同等对待:仅前端 localStorage 保存、请求体内单次传递、禁止落库落日志。 - 搜索统一抽象
SearchProvider接口;v1.0 至少实现一个即可;未配置时useOnlineSearch=true返回ERR-SEARCH-001。 - 搜索失败不阻塞主流程:返回搜索失败提示,AI 生成可降级为仅使用本地上下文。
1.9 前端编辑器(TipTap)编码规范
- 正文编辑统一使用 TipTap(基于 ProseMirror 的富文本编辑器内核),禁止自研 contenteditable 编辑层。
- 内容格式:正文以 HTML(
editor.getHTML()) 入库;AI 入参、字数统计、全文自检一律使用纯文本投影(editor.getText());material.content仍为纯文本。 - 自检 offset 基准:
/api/ai/check返回的offset以纯文本投影为准(UTF‑16 code unit);前端负责”纯文本 offset ↔ ProseMirror position”映射,替换后重取文本重建映射,禁止用 HTML 字符串下标直接定位。 - 版本 diff 基于纯文本投影(避免 HTML 标签噪声);存版快照仍存 HTML,
content_hash对存储快照计算。 - 续写 / quick 的插入与原地替换必须通过 TipTap 事务(transaction / dispatch) 执行,确保进入撤销栈,满足”可撤销 / 可回退”。
- IME:TipTap/ProseMirror 已内部处理 Composition 事件;字数统计基于
getText(),避免输入法推荐词虚增计数。 - 编辑器相关依赖(
@tiptap/vue-3及所需扩展)版本锁定,禁止跨大版本随意升级。
2 安全规范(最高优先级,红线)
本项目 v1.0 是本地单机产品:严禁将后端 8080 端口直接暴露公网;没有鉴权,暴露公网将允许外部任意人读取文档数据、盗用你的第三方 API 额度。
2.1 用户 API‑Key 安全规范(红线)
- ✅唯一来源:HTTP POST 请求体
modelConfig.apiKey;局部临时变量。 - ✅生命周期:仅单次 HTTP 请求方法内存;请求处理完成即释放。
- ❌禁止:存入成员变量、全局变量、缓存、数据库、yml 配置文件。
- ❌禁止:打印到任何日志(info/debug/trace);禁止异常堆栈打印;禁止返回报文回显。
- ✅防护手段:
- 日志层脱敏(v2.0 降级方案):不包装/篡改请求体(包装请求体会破坏 SSE 流式与框架行为),改为对送往日志的字符串统一正则脱敏(
apiKey值、sk-*、tvly-*等替换为***),作为最后一道防线。 - 代码评审:每一处日志打印、DTO/POJO 字段严格检查;禁止打印包含
modelConfig的入参 DTO 对象。 - Electron 主进程与渲染进程禁止
console打印 apiKey;前端代码评审所有 console 语句。
- 日志层脱敏(v2.0 降级方案):不包装/篡改请求体(包装请求体会破坏 SSE 流式与框架行为),改为对送往日志的字符串统一正则脱敏(
2.2 输入与提示注入安全
- SSE 事件严格白名单;不把模型原始输出直接作为后端指令执行。
- 素材 / 模板 / 版本 content 入库前校验长度与格式,且不作为指令解析执行。
- 全文自检 LLM 返回结果解析容错,不执行 LLM 返回内容中的任何”指令”。
2.3 Electron 桌面壳安全规范
- 渲染进程:
contextIsolation: true、nodeIntegration: false、sandbox: true;仅通过 preload 暴露白名单能力(文件选择、保存、窗口控制、注入 token)。 - 不加载远程网页内容;内容安全策略 CSP 收紧到仅
localhost:8080。 - 主进程与渲染进程禁止 console 打印密钥;配置存储仅 localStorage;主进程不持久化任何 apiKey。
- 应用不包含任何硬编码密钥;全部由用户设置页输入。
- 本机接口令牌(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 服务。仅绑定回环地址不足以防跨页攻击,故增加一次性令牌。
- 生成与传递闭环:后端启动生成一次性随机 token → 写入应用数据目录下的本地文件 → Electron 主进程读取 → 经 preload 注入渲染进程 → 请求头携带
X-Local-Token;token 绝不通过 HTTP 接口下发、绝不放请求体、绝不落日志/入库。 - 校验:所有业务接口(健康探测与
GET /api/system/info除外)强制校验X-Local-Token,不匹配返回401 ERR-AUTH-001。 - Host 校验:仅允许
localhost / 127.0.0.1,拒绝其他 Host(防 DNS rebinding)。 - CORS:禁用
*,仅精确匹配生产file://(Origin: null)与开发http://localhost:5173。 - 威胁模型声明:v1.0 仅防御”浏览器网页发起的跨页攻击”,不防御本机已存在的恶意程序(其可读取本地文件、拿到 token);该边界写入论文 / README。
3 配置规范
3.1 配置文件拆分
application.yml:基础服务配置、日志级别、线程池、Ollama 地址(ollama.base-url)、SQLite 连接配置(库文件路径取自数据目录,PRAGMA 见 §1.7;不存放任何用户第三方 API‑Key)。config/agent.yml:三套文体系统提示词(NOVEL/MEDIA/OFFICIAL)、续写/quick/outline/inspire 提示词模板、自检词库与格式正则、默认生成参数;启动加载 + 设置页手动重载(不做文件监听热加载,见 §1.5)。docker-compose.yml:容器编排(backend / ollama 两容器,无数据库容器);仅用于开发调试与本地部署验证,不作为桌面交付方案;区分生产docker-compose.yml与开发docker-compose.dev.yml。
3.2 配置外部化原则
- 硬编码魔法值全部抽配置;例如单次生成默认 token、SSE 超时、默认模型名、字数换算系数。
- 提示词不写死 Java 代码,全部外部化到
agent.yml;启动加载 + 设置页手动重载(不做文件监听热加载)。 - 开发/生产配置分离;生产环境关闭 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 禁止输出内容(强制)
- ❌禁止输出用户 API‑Key(含联网搜索 key);全局过滤器脱敏;业务代码也不得打印 modelConfig 完整对象。
- ❌禁止打印完整原始用户大报文(长正文可截断打印)。
- ❌禁止把第三方模型原始异常堆栈直接输出给前端;后端日志可记录完整异常,前端只展示业务 message + 错误码。
4.4 必须记录的审计日志(INFO 级别)
- 文档新建 / 删除 / 导出。
- AI 调用:记录
documentId、genre、mode(LOCAL/USER_PROVIDED_API)、耗时;不打印 apiKey。 - 全文自检执行:genre、问题数量。
- 版本存版 / 回滚:documentId、versionId。
- 配置加载 / 手动重载成功或失败;来源与结果。
- 模型模式切换事件:LOCAL / USER_PROVIDED_API;不打印 apiKey。
4.5 日志脱敏实现说明
在日志输出层做统一脱敏(如自定义 MessageConverter / Layout,或对日志字符串做正则替换):检测 apiKey 值、sk-*、tvly-* 等特征串,替换为 ***;不包装/篡改请求体(避免破坏 SSE 流式与框架行为)。
脱敏是最后一道防线;业务代码不能依赖它而放松编码约束。
5 测试规范
5.1 单元测试(收敛为 5 个关键用例)
原则:v1.0 只覆盖”改错会出红线事故”的核心路径,不追求覆盖率数字;需要 Spring 上下文的用例用
@SpringBootTest。
必测 5 个关键用例:
- ModelRouter 分支:LOCAL 模式忽略 apiKey;USER_PROVIDED_API 参数解析;异常翻译为业务错误码。
- 日志脱敏:含 apiKey 的日志行输出后确认被替换为
***。 - 自检规则引擎:各 genre 检规命中(重复用词 / 敏感词 / 口语化 / 格式),且幂等、纯函数、无 IO。
- 文档版本:
content_hash去重、回滚作为新版本追加。 - offset 映射函数:纯文本 offset ↔ ProseMirror pos 转换,覆盖换行与中英混排。
其余项(导出正确性、DTO 参数校验、配置重载回滚、字数统计等)以集成测试 / 手工回归覆盖,不单列单测,避免挤占工期。
5.2 集成测试(SpringBootTest + MockMvc)
- SSE 流式集成:续写 / quick / outline / inspire 返回
token+complete,无白名单外事件。 /api/ai/check混合自检返回结构(词级 + 语义级合并、summary)集成测试。- 文档 CRUD + 版本(存版/对比/回滚)+ 导出集成测试。
- 健康探测接口集成测试;模拟 Ollama 可用/不可用/模型缺失场景。
- 模板 / 素材 CRUD 集成测试(genre 过滤、长度校验)。
5.3 安全专项测试(交付前必须手工执行)
安全测试用例文档留存仓库
docs/security-test-cases.md。
- 密钥泄露专项测试:
- 检查应用日志,确认无明文 apiKey;
- 检查异常堆栈输出,确认不打印 apiKey;
- Electron 渲染进程开发者工具控制台,确认不打印 apiKey(含 search key)。
- 提示注入测试:素材/模板内容包含指令语句时不被后端执行。
- 异常场景测试:
- Ollama 关闭,本地模式返回友好提示;
- 用户传入错误 apiKey,返回业务错误码,不抛堆栈;
- 配置文件损坏,热加载回滚旧配置,服务不崩溃。
5.4 端到端联调测试(前后端完整链路)
- 场景 1(自有 API 模式):设置页填密钥→写作→续写→快捷处理→导出,全链路。
- 场景 2(本地 Ollama 模式):健康检测 READY→续写→全文自检→导出。
- 场景 3:Ollama 不可达(
UNAVAILABLE)/ 模型缺失(MODEL_MISSING)→ 本地模式单选置灰 → UI 引导与 FAQ。 - 场景 4:SSE 断连重连;网络异常友好降级。
- 场景 5:崩溃/重启恢复草稿;存版/对比/回滚;导出。
- 场景 6(AI 赋能全景):文体切换→模板生效→大纲生成跳转→素材收藏插入→划选 quick 四操作→全文自检标红替换→暗色/悬浮字数→参数双预设切换。
- 场景 7(桌面进程编排,R1):冷启动显示遮罩直至后端就绪;关闭应用后无残留 java 进程、8080 端口已释放;运行中强制 kill 后端 → UI 提示并自动重启;二次启动不报端口冲突。
5.5 测试禁止
- 单元/集成测试用例不要写入真实有效的第三方 apiKey;全部使用 mock。
- 不要提交包含真实密钥的配置文件到 Git 仓库;gitignore 屏蔽本地 yml。
6 构建与部署规范
6.1 Git 版本管理规范
- main 为主分支;开发分支 develop;每个里程碑完成打 Git Tag:v0.1 ~ v1.0。
- commit 规范:feat / fix / refactor / test / docs / security。
- gitignore 配置:忽略本地
application-local.yml、日志目录、docker 环境文件、前端node_modules。 - 严禁把任何真实密钥提交 Git 仓库。
6.2 Maven 构建规范
- maven profile 区分 dev / prod。
- prod 打包:关闭 dev 调试端点;日志级别 INFO;剔除测试类;构建可执行 jar。
- 构建产物:后端 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 版本对外提供服务;无鉴权会造成严重安全风险。
部署步骤文档:
- 执行
docker compose up -d(首次启动自动初始化 SQLite 表结构:Flyway/SQL 脚本执行建表,库文件生成于挂载的./data/writer.db); - Ollama 容器需要手动执行
ollama pull qwen2.5:3b下载对话模型;镜像不会内置大模型;文档写清楚; - 启动成功后桌面应用设置页后端地址填写
http://localhost:8080; - 打开应用健康检测,确认本地模型就绪(或直接在设置页填入自有 API 密钥);
- 两种使用路径说明:自有 API 开箱即用 / 本地 Ollama 模式需要 pull 预训练模型,不需要训练模型。
6.4 容器镜像优化
- backend 镜像采用 jre21 精简基础镜像;不要完整 JDK。
- 分层构建;maven 依赖层缓存,加速构建。
- Ollama 镜像使用官方 ollama 镜像;模型数据卷持久化;不要把模型打进镜像层。
6.5 Electron 桌面端打包规范
- 前端工程:Vite + Vue3 构建 dist → 由 electron‑builder 打包为 Windows NSIS 安装程序(.exe);同时产出免安装 zip 便于分发。
- 渲染进程安全基线:contextIsolation、sandbox 开启,nodeIntegration 关闭;打包产物启用 ASAR。
- 应用不内置 Ollama 与模型;首次使用引导用户安装 Ollama / 或直接填自有 API 密钥。
- 打包产物命名带版本号(
Writer-Assistant-Setup-1.0.0.exe);安装后生成桌面快捷方式与开始菜单项。 - 后端与 JRE 随包分发:用
jlink裁剪最小 JRE(约 50‑90MB),与后端 jar 一并放入 electron‑builder 的extraResources;主进程用该 JRE 启动 jar,不依赖用户电脑预装 JDK21。v1.0 仅编译 Windows x64 一份。 - 进程管理依赖:引入
tree-kill(Windows 等价taskkill /T /F),退出时杀整棵 Java 进程树;主进程用spawn(java, [...], { shell:false })使 java 成为直接子进程,保证child.kill()有效。 - 打包后路径:所有资源路径用
app.getPath('userData')动态获取,禁止写死相对路径;数据目录经--writer.data-dir传给后端(见 §6.7)。 - 打包后冒烟测试(不可省略):安装 → 启动遮罩 → 后端就绪 → 写作/续写 → 导出 → 退出无残留进程;列入交付清单必备项。
6.6 部署交付物清单
- 后端可执行 jar;
- Windows x64 桌面安装包(NSIS .exe)+ 免安装 zip(内含 jlink 裁剪 JRE 与后端 jar)——正式交付形态;
- docker-compose.yml + docker-compose.dev.yml(含 backend/ollama 两容器)——仅开发调试用,非交付主形态;
- SQLite 四表建表 SQL / Flyway 迁移脚本;
- 样例
agent.yml(含三套文体提示词)、demo 文档; - 全套 Markdown 文档:01 需求 / 02 接口 / 03 生产规范 / 04 工作计划表 / 故障排查清单 / 安全测试用例;
- 打包后冒烟测试记录;
- 演示录屏。
6.7 桌面交付与进程编排(R1 / R7)
后端 jar 是随桌面应用启动的本地 Java 进程,不是独立服务;其生命周期由 Electron 主进程统一编排,否则会出现”关窗后 Java 残留、8080 被占用、二次启动失败”。
(一)进程编排
- 拉起:主进程
spawn(javaFromJlink, ['-jar', backendJar, '--writer.data-dir=<userData>/data'], { shell:false })——不套 shell,java 即直接子进程,child.kill()有效。 - 杀进程树:额外用
tree-kill(Windows 等价taskkill /T /F)兜底,退出时杀整棵 Java 进程树,避免残留线程占用端口。 - 启动遮罩:窗口先渲染遮罩,轮询健康接口(
/api/status/local-model或/api/system/info)直至就绪;未就绪禁止显示编辑器,失败显示错误与重试。 - 崩溃自愈:监听
child.on('exit'/'close'),非主动退出判定为崩溃 → 自动重启 + UI 提示;多次失败提示手动排查。 - 残留端口回收:启动前检测 8080,若为上次残留则回收再启动。
- 优雅停机:JVM 注册
ShutdownHook;后端暴露 shutdown 端点(仅 127.0.0.1);退出时先调 shutdown 接口,失败再tree-kill强杀。
(二)数据目录与路径(R7)
- Electron 主进程传
--writer.data-dir=<userData>/data;Java 侧WriterHome解析顺序:启动参数 → 环境变量 →user.home兜底。 - 配置
agent.yml、SQLitewriter.db、token 文件全部落在该目录;严禁写死相对路径(开发环境跑通、打包后路径全变是典型坑)。 - 打包后必须做冒烟测试(见 §6.5-8),不能只靠开发环境联调。
7 运维与故障排查规范(v1.0 单机个人使用)
7.1 v1.0 运维限制说明
v1.0:文档 / 版本 / 模板 / 素材全部存本机 SQLite 单文件(应用数据目录下
writer.db,见 §6.7);重启 backend 后数据仍在;数据即本地文件,备份即复制该文件;无独立数据库服务,不存在”数据库服务未启动”故障面。文档显著位置提示用户定期备份该.db文件。
7.2 常见故障排查清单(写入交付 README)
- 桌面应用健康检测显示 Ollama 未连接:检查 ollama 容器 / 本地 ollama 是否启动;地址是否与配置项
ollama.base-url一致(宿主机 127.0.0.1:11434 / 容器 ollama:11434); - 本地模式就绪但续写报错 OOM:内存不足;切换 qwen2.5:1.5b 小模型;
- 自有 API 模式报错密钥错误:确认应用设置页 apiKey、baseUrl、modelName 填写正确;用【测试连通性】按钮校验;
- 修改
agent.yml配置不生效:v1.0 无文件监听热加载,需在设置页点【重载配置】或重启应用;配置解析失败会回滚旧配置,查看应用日志 INFO 的加载日志; - backend 重启后文档打不开:检查数据目录下 SQLite 库文件是否被删除或权限不足(桌面模式
<userData>/data/writer.db;开发容器模式挂载的/app/data/writer.db); - 访问 8080 来自其他机器连接被拒绝:这是预期安全行为,v1.0 只允许本机 localhost 访问;
- 全文自检无结果:确认 genre 是否选择(检规按 genre 加载);LLM 语义检查失败时仍应返回规则引擎结果;
- 导出 word 乱码/格式异常:确认使用 POI XWPF 生成,字体使用通用字体;v1.0 仅支持基础标题/段落排版,复杂样式请导出后自行处理。
- 应用启动一直显示”后端正在启动”:首次 JVM 冷启动较慢(耐心等待)或后端启动失败;查看日志,尝试重启应用;若提示端口被占用,多为上次残留进程,关闭其他实例后重试。
- 关闭应用后 java 进程残留 / 8080 被占:属 R1 编排故障;确认主进程已接入
tree-kill并在退出时先调 shutdown 端点、失败再强杀;临时可手动结束残留进程。 - 请求返回
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
- 后端:配置目录
./config手动备份;SQLite 库文件定期备份(直接复制writer.db,或执行VACUUM INTO 'backup.db'生成一致性快照;WAL 模式下建议在无写入时复制,或一并复制writer.db-wal/writer.db-shm); - 桌面应用:设置页导出 JSON 配置备份(包含用户 apiKey,备份文件妥善保管,不要公开)。
v1.0 没有自动备份功能,全部手动备份;文档写明。
8 版本发布流程规范
8.1 里程碑发布流程(v0.1~v1.0)
- 完成阶段全部开发;
- 执行全部单元测试 + 集成测试;全部通过;
- 执行安全专项测试;安全用例全部通过;
- 更新对应文档(需求、接口、生产规范、工作计划表同步版本号);
- Git commit 全部变更;打对应 Tag;
- 构建 docker 镜像、Electron 打包产物;
- 编写本版本变更日志 CHANGELOG.md;
- 里程碑验收;记录已知限制、MVP 边界;
- 交付归档。
8.2 CHANGELOG.md 规范
每个版本记录:新增功能、修复 bug、安全修复、不兼容变更、MVP 已知限制。
9 MVP 已知限制清单(部署文档显著位置必须展示)
v1.0 明确限制,避免用户产生错误预期;全部写入 README 首页。
- 文档 / 版本 / 模板 / 素材全部存本机 SQLite 单文件:数据即本地文件(
writer.db),无需安装数据库服务;建议定期复制该文件备份,文件损坏或被误删需从备份还原。 - v1.0 没有用户登录鉴权;后端端口只能绑定 127.0.0.1 本机访问;严禁暴露公网;公网使用需要完整鉴权体系(v1.2 SaaS 分支)。
- 无法按每个用户传入的第三方 API‑Key 独立统计配额;用户额度请到第三方模型服务商控制台查看。
- Electron 桌面应用不自动安装 Ollama、不自动执行终端下载模型;本地模式需要用户手动安装 Ollama 并 pull 预训练模型,不需要训练模型。
- AI 能力为单轮短链调用,不提供多 Agent 自动编排、自动写文件流水线;AI 产出需用户确认后手动采纳。
- v1.0 仅交付 Windows x64(Windows 10/11),不提供 macOS / Linux 安装包;不做浏览器扩展、不做网页划词。
- 卸载应用会丢失 localStorage 中全部配置(含 apiKey、写作参数预设、自动缓存草稿);需要用户提前导出 JSON 备份。
- 联网素材为外部依赖项:需用户申请第三方搜索 API 并在设置页填入 key;key 未配置时联网开关置灰,不影响本地模式与其他功能。
- 历史版本仅「手动存版 + 会话结束自动存一版」;doc_version 内容上限与素材条数受本机 SQLite 文件与本机磁盘容量限制,超存量建议手动清理。
- v1.0 不使用 Redis、不提供本地文档 RAG 知识库、不提供多会话隔离;素材库检索作为 v1.1 可选增强。
- word 导出为结构化降级(标题 + 段落),不支持复杂样式 / 图文混排;如需复杂排版请导出后自行处理。
- 打字机模式、LLM 语义级自检、联网素材搜索、配置文件监听热加载属 P2,v1.0 不承诺交付(有余力再做)。
- 后端以 Java 进程随应用启动,安装包含 jlink 裁剪 JRE,整机约需数百 MB 磁盘;冷启动需数秒,期间显示启动遮罩。
- 后端为随应用启动的本地进程,仅支持单进程独占 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(结构化降级)。