第一次启动请先看 Windows 从零启动手册。 已按当前电脑环境说明 .env、pgvector、Docker 与本机开发两条路线、IDE 设置和排错。电脑已有 PostgreSQL 占用 5432 时，Docker 路线使用手册中的 compose.windows.yaml 端口覆盖配置。
Vue + Spring Boot + Python 实现的共享知识库。管理员上传文档，成员检索问答，答案显示引用，每个人只能访问自己的会话。
学习源码请阅读 项目结构与源码详解，其中逐一说明目录、文件、Java 类与方法、Python 函数、Vue 组件、数据库字段和业务调用链。
后端现已采用 MyBatis + XML，按 controller → service / impl → mapper 分层。详见 MyBatis 迁移与验收说明。数据库表和前端 API 保持兼容。
需要 Docker Engine / Docker Desktop 和 Docker Compose v2。
Copy-Item .env.example .env
# 编辑 .env，填写数据库密码、管理员密码、内部令牌及模型配置
docker compose up --build -d
docker compose ps访问 http://localhost:8088 ，使用 .env 中的管理员账户登录。管理员密码至少 12 个字符，内部令牌至少 32 个字符。演示配置的数据库密码使用字母、数字和短横线，避免 URL 保留字符。不要提交 .env。
启动顺序为数据库 → Spring Boot（Flyway 自动迁移、初始化管理员）→ AI 服务及 worker → 前端。首次构建需要下载依赖。默认数据库与后端调试端口仅绑定本机，Python 服务不对外开放。
如果暂时没有模型密钥，将 MODEL_MOCK=true。模拟模式使用确定性字符向量及资料摘录，回答会标记“模拟模式”；它只能检查流程，不能检验 AI 效果。模拟模式切换到真实模型时需要重建索引。
问答模型需要支持 OpenAI 兼容的 POST /chat/completions 和流式输出，向量模型需要支持 POST /embeddings。两者可以来自不同服务商。
| 配置 | 用途 |
|---|---|
CHAT_BASE_URL / CHAT_API_KEY / CHAT_MODEL |
问答与追问改写；地址一般以 /v1 结尾，不包括 /chat/completions |
EMBED_BASE_URL / EMBED_API_KEY / EMBED_MODEL |
文档及问题向量；地址不包括 /embeddings |
EMBED_DIMENSION |
必须与向量模型实际输出维度一致，不是自动请求模型压缩维度 |
MODEL_MOCK |
默认 false；true 只用于流程验证 |
CHUNK_SIZE / CHUNK_OVERLAP / TOP_K |
Python 可选环境变量，默认 800 / 120 / 6 |
部分服务商仅提供问答模型，不提供向量模型，需要另外配置。密钥在模型服务端使用，不会返回浏览器。请求会把检索到的资料发送给所配置的在线服务。
修改 .env 后执行 docker compose up -d --force-recreate ai worker。向量服务地址、模型名称或维度改变后，系统拒绝混用索引；执行：
docker compose exec ai python -m app.indexing该命令会清空并重建向量片段，原文件、账户和会话保留。重建期间暂停问答，全部未删除文档成功处理后恢复。失败文档在管理页面重试，或删除后由 worker 自动完成重建状态切换。
需要 JDK 21、Maven 3.9+、Node.js 22.12+、Python 3.12，以及 Docker 数据库。代码也已考虑 Python 3.13 的本地环境。将 Java 和 Maven 放入 PATH，并设置 JAVA_HOME。
Copy-Item .env.example .env
# 编辑配置后，仅启动数据库
docker compose up -d db
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r ai\requirements.txt
Set-Location frontend
npm ci
Set-Location ..分别打开四个 PowerShell 窗口，在项目根目录运行：
.\scripts\dev.ps1 backend
.\scripts\dev.ps1 ai
.\scripts\dev.ps1 worker
.\scripts\dev.ps1 frontend先等 backend 启动完成再启动 Python。前端访问 http://localhost:5173 。脚本读取 .env 并统一设置本机数据库和文档路径；环境变量值不要额外加引号。Windows 与容器使用不同的文档存储，不要把两套部署同时连接到同一数据库进行写入。
- 登录使用 Spring Security Session、HttpOnly Cookie 和 CSRF；账户禁用会在后续请求时使已有会话失效。已在生成中的回答允许结束。
- 一个共享知识库。普通用户只能查看已完成入库的文档；管理员负责上传、删除、重试及账户管理。
- PDF 使用 pypdf 提取文本并保留页码，DOCX 使用 python-docx 保留段落/表格定位，Markdown 保留标题路径。不做 OCR，不承诺恢复复杂排版。
- PostgreSQL 保存业务数据与 pgvector 向量。Flyway 统一维护表结构，JPA 管理用户，JdbcTemplate 处理流式消息和任务事务。
- worker 通过数据库领取任务，120 秒租约、25 秒续租，连续中断最多尝试 3 次，之后人工重试。片段事务替换，提交前检查文档删除状态和租约令牌。
- 删除先停用检索，再清理片段及原文件。历史引用保留原文快照，但标记来源已删除。
- 追问使用最近 6 轮完成的对话改写检索问题，余弦距离精确检索前 6 个片段。第一版没有重排序、混合检索或相关性阈值；无依据回答的质量需要用真实模型评估。
- POST + Fetch/SSE 返回回答。逐段保存内容，超时或断开标记未完成；同一会话只能同时生成一个回答。重启遗留的流式消息约 4–5 分钟内恢复为未完成。
- 管理员初始账户只在不存在时创建，修改环境变量不会重置已有密码。第一版不包含密码找回和账户自助改密。
核心目录：frontend 为界面，backend 为 Java 业务服务，ai 为 FastAPI 和 worker，scripts 为开发工具，examples 为演示资料及评估集。详细接口见 docs/api.md。
# Python 单元测试
Set-Location ai
..\.venv\Scripts\python.exe -m pytest -q
Set-Location ..\frontend
npm test
npm run build
Set-Location ..\backend
mvn test
mvn package启动完整服务后，从根目录运行端到端检查（需 SMOKE_ADMIN_PASSWORD 环境变量；不要把密码写入命令历史）：
.\.venv\Scripts\python.exe scripts\smoke.py该检查会在本机部署创建两个测试账户、上传演示 Markdown 并发起问答，验证 CSRF、权限隔离、下载、删除和引用。测试文档、会话会清理，测试账户会禁用；普通账户不提供删除接口。请在学习环境运行。连接默认 http://localhost:8088，可通过 SMOKE_BASE_URL 修改；模拟模式可检查流程，真实模式回答内容仍需人工评估。
按 examples/evaluation.md 的 30 题进行真实质量验收。目标：有答案 ≥16/20，无答案 5/5，连续追问 ≥4/5。模拟模式不计入成绩。
数据库集成测试需要单独测试库和 TEST_DATABASE_URL，随后在 ai 目录运行 python -m pytest tests/test_database.py -q。测试在随机 schema 中建表并清理，需允许安装 vector 扩展；不要连接生产库。未设置测试库时这 4 项测试明确跳过。当前执行结果见 docs/verification.md。
docker compose logs --tail 100 backend ai worker
docker compose ps
docker compose stop
docker compose start日志记录请求/任务 ID、耗时、错误类型，不输出密钥和完整资料。/actuator/health 检查后端，AI /health 检查数据库连通性。文件与数据库使用命名数据卷，普通重启和 docker compose down 保留数据；不要执行 down -v，它会删除数据卷。
为得到一致备份，需要停止应用写入，同时保存数据库和文档卷；只备份数据库无法恢复原始文件。
推荐直接执行 scripts/backup.ps1，它会停止应用、生成数据库及文档归档并恢复应用。备份期间不可访问。恢复到新部署：先启动数据库，复制 dump 到 db 容器，通过 pg_restore --clean --if-exists -U knowledge -d knowledge /tmp/knowledge.dump 恢复；将文件归档解压到 backend 的 /data，确认 /data/documents 归属 app 用户，再启动其余服务。密钥和 .env 单独安全保管。
这是个人学习项目，未提供公网 HTTPS、水平扩容或生产性能承诺。部署真实数据前应更新并审计依赖，并完成自己的质量和权限验收。