WIKI 本地知识库从 v1.0.0 升级到 v1.1.0，不只是替换一份程序文件。新版本将前端控制台收敛到 frontend/，把配置作为优先入口放到 conf/，并将业务接口统一到 /api 前缀。对于已经上线 v1.0.0 的环境，迁移重点是保护知识库数据、显式确认存储路径，并逐项修正反向代理、前端构建和二次开发调用。
先确定哪些内容可以原样保留
已有的知识库数据，例如 kb_store/ 及其关联文件，一般可以直接沿用。真正需要确认的是运行时配置：数据目录并不应仅凭默认目录推断，而应以 knowledge_base.storage 一类的配置项为准。
升级前建议完成三个动作：
- 停止写入任务，避免导入、切分或索引构建在备份过程中产生半成品。
- 备份数据目录和当前配置目录；数据备份不能替代配置备份。
- 记录当前服务地址、反向代理规则和调用接口，后续用来做回归验证。
可以按下面的方式制作一次带时间戳的迁移快照。运行前将 /srv/wiki 替换为实际部署目录，并确认 kb_store/ 与 conf/ 的位置和配置一致。
#!/usr/bin/env bash
set -euo pipefail
APP_DIR=/srv/wiki
BACKUP_DIR=/srv/wiki-backups/$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
# 停止方式请替换为实际的 systemd、Docker Compose 或进程管理命令
# systemctl stop wiki
cp -a "$APP_DIR/conf" "$BACKUP_DIR/conf"
cp -a "$APP_DIR/kb_store" "$BACKUP_DIR/kb_store"
sha256sum "$BACKUP_DIR"/conf/* > "$BACKUP_DIR/conf.sha256" || true
find "$BACKUP_DIR/kb_store" -type f -print0 | sort -z | xargs -0 sha256sum > "$BACKUP_DIR/kb_store.sha256"
printf 'Backup completed: %s\n' "$BACKUP_DIR"
如果知识库实际目录由 knowledge_base.storage 指向其他挂载卷，脚本中的 kb_store 必须替换为该真实路径。不要只备份代码目录后就删除旧环境的数据卷。
配置优先：把运行参数集中到 conf/
v1.1.0 的工程结构强调 conf/ 是配置入口。迁移时应避免将环境差异散落在启动脚本、前端源码或反向代理临时规则中。较稳妥的做法是：将旧版本仍有效的业务参数整理进新版本的 conf/，再以新版本提供的配置样例和字段定义为准逐项核对。
下面是一个用于说明迁移意图的配置示例，不代表项目的唯一配置格式。关键点在于将知识库实际存储位置显式写入配置，并让服务、脚本和运维文档引用同一个值。
# conf/application.yaml
knowledge_base:
storage: /data/wiki/kb_store
server:
host: 0.0.0.0
port: 8080
迁移时特别检查这些问题：
- 容器环境中的
/data/wiki/kb_store是否正确挂载到宿主机持久卷。 - 服务进程是否拥有读写知识库目录的权限。
- 旧版本的配置键是否已经改名、分组或废弃。对于来源中未明确列出的字段，应以 v1.1.0 的配置模板和启动日志为准，而不是机械复制旧文件。
- 开发、测试、生产环境是否误用了同一个存储目录，避免测试索引污染生产数据。
frontend/ 带来的控制台调整
v1.1.0 将 Vue 控制台放在 frontend/。这意味着前端依赖安装、构建产物和环境变量应以这个目录为工作目录。部署脚本如果仍在仓库根目录执行前端命令，可能会得到错误的依赖解析结果，或者根本没有生成控制台资源。
可以这样实践一次干净构建。命令默认项目使用 Node.js 包管理器；实际应优先遵循仓库中的锁文件，例如存在 pnpm-lock.yaml 时使用 pnpm。
cd /srv/wiki/frontend
# 按仓库锁文件选择对应包管理器
npm ci
npm run build
# 检查构建产物是否生成；具体目录以项目配置为准
find . -maxdepth 2 -type d \( -name dist -o -name build \) -print
如果控制台由 Nginx 提供静态文件，还应确认 Nginx 的 root 已指向新版构建产物，而不是 v1.0.0 中遗留的目录。前端部署完成后，至少手工验证登录页、知识库列表、文档上传或管理入口等核心路径是否能正常访问。
业务 API 统一到 /api 后，代理和调用方都要改
接口统一使用 /api 前缀时，最容易遗漏的是两类调用方：反向代理的路径转发规则，以及二次开发中的硬编码请求地址。前端页面能打开并不表示业务请求正常，浏览器开发者工具中出现大量 404 或错误跨域请求，通常就是旧路径仍在生效。
以下 Nginx 配置展示了一个常见的拆分方式：控制台静态资源由 Nginx 托管，所有 /api/ 请求转发给后端。后端地址、构建目录和超时参数需要按实际环境调整。
server {
listen 80;
server_name wiki.example.internal;
root /srv/wiki/frontend/dist;
index index.html;
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 120s;
}
location / {
try_files $uri $uri/ /index.html;
}
}
二次开发的请求封装也应把 /api 作为统一基路径。例如，避免分别在每个调用点拼接旧路径：
const apiBase = process.env.WIKI_API_BASE || "/api";
export async function getKnowledgeBases() {
const response = await fetch(`${apiBase}/knowledge-bases`, {
headers: { Accept: "application/json" }
});
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
return response.json();
}
示例中的 /knowledge-bases 仅用于展示路径拼接方式。具体资源路径、认证头和请求参数应保持与 v1.1.0 实际 API 定义一致。若旧网关曾通过 rewrite 去掉某个前缀，也要重新审查，避免把 /api 又错误剥离掉。
用一轮回归验证结束迁移
升级完成后，不建议只看服务进程是否启动。应同时验证数据可见性、写入能力、控制台资源和 API 路由。一个最低限度的检查清单如下：
- 配置中的知识库存储路径与实际挂载目录一致，且原有知识库能够被识别。
- 控制台静态资源来自新版
frontend/的构建结果。 /api前缀的请求能正确抵达后端，旧代理规则没有造成重复前缀或路径丢失。- 选择一份已有文档执行检索，并在隔离环境导入一份测试文档，确认读写链路都正常。
- 保留 v1.0.0 的数据备份和可回退部署材料，直到业务验证完成。
这次升级的核心取舍很明确：数据通常可以延续，但工程入口发生了收敛。把存储路径放进配置、把前端操作固定在 frontend/、把所有业务调用收敛到 /api，能让后续部署和二次开发少依赖隐含约定，也让故障排查有清晰的落点。