Windows 与 Linux 部署

Java MossKB 由三部分组成：PostgreSQL 保存业务数据与向量，Java 后端提供 HTTP、SSE 与静态资源接口，前端是复用官方界面的静态页面。推理、向量和 OCR 全部由远程服务完成，本机不需要加载模型权重。Windows 与 Linux 的差别只在工具链的安装方式和启动方式，数据库结构与配置文件完全相同。

先准备数据库，再准备配置，然后初始化，最后构建启动。四步在两种系统上顺序一致。

一、准备数据库

数据库需要 vector（pgvector）和 pg_trgm 两个扩展。扩展以数据库为单位注册，并且必须装在实际运行 PostgreSQL 的那台机器上：只在客户端装依赖、只执行 CREATE EXTENSION 都不能补上服务端缺失的二进制文件。缺少扩展时的报错是 extension "vector" is not available。

1.1 Windows：编译安装 pgvector

1. 确认实际运行的 PostgreSQL 安装目录。执行 SELECT version(); SHOW data_directory;，并检查 Windows 服务的可执行文件路径。
2. 安装 Visual Studio Build Tools 的 C++ 工具，打开 x64 Native Tools Command Prompt。
3. 从 pgvector 官方仓库 获取源码。将 PGROOT 指向正在运行的 PostgreSQL 安装目录；编译架构应与数据库一致。

set "PGROOT=D:\Program Files\PostgreSQL\<实际主版本目录>"
git clone https://github.com/pgvector/pgvector.git
cd pgvector
nmake /F Makefile.win
nmake /F Makefile.win install

安装后，目标 PostgreSQL 目录中应存在 lib/vector.dll、share/extension/vector.control 及相应 SQL 文件。然后连接业务数据库启用扩展：

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

SELECT extname FROM pg_extension WHERE extname IN ('vector', 'pg_trgm');
SELECT '[1,2,3]'::vector;

1.2 Linux：安装 PostgreSQL 与 pgvector

Debian / Ubuntu 上可以直接用发行版仓库安装数据库本体，pgvector 用源码编译最稳妥，版本不受发行版打包进度影响。

sudo apt update
sudo apt install -y postgresql postgresql-contrib build-essential git make gcc

# 编译 pgvector 需要与已安装主版本一致的开发包，主版本用 pg_config --version 查看
# 例如 PostgreSQL 16 对应 postgresql-server-dev-16
sudo apt install -y postgresql-server-dev-<主版本>

git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

make install 需要写 PostgreSQL 的 lib 与 share/extension 目录，所以要用 sudo；如果一台机器上装了多个主版本，用 make install PG_CONFIG=/usr/lib/postgresql/<主版本>/bin/pg_config 指定目标版本。部分发行版（例如 PGDG 仓库）直接提供 postgresql-<主版本>-pgvector 包，也可以用它替代编译安装。

安装完成后创建业务数据库并启用扩展：

sudo -u postgres psql -c "CREATE DATABASE moss_kb;"
sudo -u postgres psql -d moss_kb -c "CREATE EXTENSION IF NOT EXISTS vector;"
sudo -u postgres psql -d moss_kb -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

为应用创建一个独立账号，避免直接用超级用户：

sudo -u postgres psql -c "CREATE USER moss_kb WITH PASSWORD '<数据库密码>';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE moss_kb TO moss_kb;"
sudo -u postgres psql -d moss_kb -c "GRANT ALL ON SCHEMA public TO moss_kb;"

1.3 让 WSL 与其它主机连上数据库

数据库只监听 127.0.0.1 时，只有本机能连。要让 WSL 里的 Linux、局域网里的另一台机器或容器连过来，需要同时放开监听地址和认证规则。

postgresql.conf：

listen_addresses = '*'

pg_hba.conf 追加一行，网段按实际情况收窄（下例放行 WSL 私网地址段）：

# TYPE  DATABASE   USER   ADDRESS          METHOD
host    all        all    172.16.0.0/12    scram-sha-256

两条配置都不需要重启数据库，重载即可生效：

SELECT pg_reload_conf();

Windows 上如果服务只监听本机，还要确认防火墙放行 5432 端口。用管理员身份执行一次，只放行私网来源：

New-NetFirewallRule -DisplayName 'PostgreSQL 内网访问' -Direction Inbound -Protocol TCP `
  -LocalPort 5432 -RemoteAddress 172.16.0.0/12 -Action Allow

这一步只用于本地验证；面向公网时应当只开内网地址段，或者改用只允许本机连接的隧道方式。WSL 里的 Linux 要连宿主机的数据库时，这三项缺一不可：listen_addresses、pg_hba.conf 里的来源网段、以及这条防火墙规则。

WSL 里 127.0.0.1 指的是 WSL 自己，宿主机是 WSL 的默认网关地址，所以这种情况下 jdbc.url 要写网关地址而不是回环地址：

ip route show default | awk '{print $3}'      # 例如 172.28.32.1

jdbc.url=jdbc:postgresql://172.28.32.1:5432/moss_kb

WSL 每次重启后网关地址可能变化，脚本里用上面那行命令取值即可，不要写成固定地址。

二、本地配置

后端启动时读取 mosskb-web/my.txt，每行一项；# 开头是注释。

jdbc.url=jdbc:postgresql://127.0.0.1:5432/<实际数据库名>
jdbc.user=<数据库用户>
jdbc.pswd=<数据库密码>
app.admin.secret.key=<本机生成的随机签名密钥>
server.port=10060
app.env=dev
jdbc.showSql=false

数据库名、用户和密码都使用连接配置中的实际值，不依赖项目名称。app.admin.secret.key 用于签发登录令牌，换掉它等于让全部旧令牌失效。远程模型密钥放在相邻的 secrets.txt：

GITEE_API_KEY=<自己的密钥>

两个文件都保持在 Git 忽略列表中，不把密钥复制到前端环境文件、SQL、截图或文档。Linux 上建议把权限收紧到只有运行用户可以读：

chmod 600 mosskb-web/my.txt mosskb-web/secrets.txt

隔离 Python 执行器的配置项也在 my.txt，见隔离 Python 执行环境配置。

三、初始化数据库

db 目录下的三个脚本都是幂等的，Windows 与 Linux 使用同一套 SQL。

执行顺序是 schema.sql → seed.sql；需要清空重建时在前面加 reset.sql。初始化脚本会读取 my.txt 的连接参数，按顺序执行它们：

# Windows：-PostgresBin 省略时使用 PATH 上的 psql
.\scripts\Initialize-Database.ps1
.\scripts\Initialize-Database.ps1 -PostgresBin 'D:\Program Files\PostgreSQL\18\bin'

# 清空业务表后重建
.\scripts\Initialize-Database.ps1 -Reset

# Linux / WSL，需要先安装客户端：sudo apt install -y postgresql-client
./scripts/Initialize-Database.sh
./scripts/Initialize-Database.sh --reset

也可以直接用 psql 执行，适合脚本化部署：

export PGPASSWORD='<数据库密码>'
psql -h 127.0.0.1 -p 5432 -U moss_kb -d moss_kb -v ON_ERROR_STOP=1 -f db/schema.sql
psql -h 127.0.0.1 -p 5432 -U moss_kb -d moss_kb -v ON_ERROR_STOP=1 -f db/seed.sql

初始化完成后 public 下有 29 张表。默认模型配置如下：

选择向量模型时兼顾中文文档检索与服务部署成本；本方案采用较大参数规模的远程模型，并使用 1024 维存储。模型质量仍应以自己的知识库测试集评估。向量缓存同时保存模型标识、维度和内容摘要，更换向量模型或维度后必须重新生成已有文档的向量，不能混用不同向量空间。模型 ID 和可用性以平台当前模型列表为准。

升级已有数据库时直接重复执行两个脚本即可，它会补齐缺失的表、列和索引，不会删除数据。结构变化较大的版本仍应先备份，再在测试库上验证。

四、Windows 部署

4.1 环境要求

Docker 只有隔离 Python 执行功能需要，且不必装在本机，见隔离 Python 执行环境配置。

4.2 目录结构

后端仓库与前端仓库放在同一个父目录，后端脚本按相对路径找前端：

project-mosskb/
  java-mosskb/
    db/                   数据库结构与初始数据脚本
    mosskb-business/       业务逻辑与测试
    mosskb-web/            HTTP 入口、本地配置与运行日志
    scripts/             初始化、启动、目录同步与补丁导出
    docs/                验证记录与定制说明
  java-mosskb-ui/
    src/                  前端源码
    env/                  前端环境文件

4.3 构建

先在 java-mosskb-ui 安装前端依赖：

npm install

再在 Java 仓库根目录构建后端：

mvn clean '-Dmaven.test.skip=true' '-Dmaven.javadoc.skip=true' '-Dgpg.skip=true' -Pproduction package

构建产物是 mosskb-web/target 下的可执行 JAR。也可以让启动脚本带着构建一起做：

.\scripts\Start-Local.ps1 -Build

需要指定本地可执行文件时，传入 -JavaExecutable、-NodeExecutable、-MavenExecutable。

4.4 启动

.\scripts\Start-Local.ps1

脚本在后台启动 Java 与 Vite，并复用已经在监听的端口。默认地址：

• 前端：http://localhost:3000/ui/
• 后端：http://localhost:10060
• 后端日志：mosskb-web/logs/startup.log、startup-error.log
• 前端日志：java-mosskb-ui/.local/vite.log、vite-error.log

修改代码后应先停止属于本项目的旧进程，再重新构建启动。后端运行工作目录是 mosskb-web，本地配置就是从这里被读到的。

4.5 首次登录

初始管理员凭据沿用数据库设计的种子数据：用户名 admin，初始密码以该章记录的值为准，登录后应立即修改。登录后可看到系统管理中的模型设置，默认写入的两个模型说明初始化脚本执行成功。

五、Linux 部署

Linux 与 WSL 使用同一套 Shell 脚本，步骤与 Windows 一致，区别只在安装工具链的方式。下面的命令在一台干净的 Ubuntu 上依次执行即可。

5.1 环境准备

sudo apt update
sudo apt install -y openjdk-21-jdk maven nodejs npm postgresql-client git

java -version
mvn -v
node -v
npm -v
psql --version

需要注意两点：

• 发行版仓库里的 Node.js 版本过旧时，用 NodeSource 或 nvm 安装较新的版本，前端构建对 Node.js 版本有要求。
• psql 只用来执行初始化脚本，可以装在与数据库不同的机器上，用 -h 指定数据库地址即可。

国内网络加速

默认源在国外，装一套工具链要等很久。实测同一批软件包：走 archive.ubuntu.com 时 34.6 MB 用了约 5 分钟（88 kB/s），换成中科大镜像后同样内容 15 秒完成（2.3 MB/s）。换源只改文件内容，不影响后续步骤。

Ubuntu 24.04 及以后用 deb822 格式，把 /etc/apt/sources.list.d/ubuntu.sources 里的地址整体替换即可：

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.orig
sudo sed -i \
  -e 's|http://archive.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' \
  -e 's|http://security.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' \
  /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

更早的版本改 /etc/apt/sources.list，把 archive.ubuntu.com 与 security.ubuntu.com 换成同一个镜像地址。清华、阿里云的镜像用法相同，把域名换掉即可。

前端依赖走 npm，同样可以换到国内镜像：

npm config set registry https://registry.npmmirror.com
npm config get registry

Maven 依赖可以在 ~/.m2/settings.xml 里加一个阿里云镜像，构建后端时从国内下载：

<settings>
  <mirrors>
    <mirror>
      <id>aliyun</id>
      <name>aliyun maven</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

三个源都是可选项：内网已经有代理或私有仓库时按现有设施配置即可。

5.2 获取代码与配置

mkdir -p /opt/java-mosskb && cd /opt/java-mosskb
git clone <后端仓库地址> java-mosskb
git clone <前端仓库地址> java-mosskb-ui

cd java-mosskb
cat > mosskb-web/my.txt <<'EOF'
jdbc.url=jdbc:postgresql://127.0.0.1:5432/moss_kb
jdbc.user=moss_kb
jdbc.pswd=<数据库密码>
app.admin.secret.key=<本机生成的随机签名密钥>
server.port=10060
app.env=dev
jdbc.showSql=false
EOF

cat > mosskb-web/secrets.txt <<'EOF'
GITEE_API_KEY=<自己的密钥>
EOF

chmod 600 mosskb-web/my.txt mosskb-web/secrets.txt

前端与后端必须是同一父目录下的两个目录，scripts/Start-Local.sh 才能找到前端。数据库不在本机时，把 jdbc.url 指向数据库地址。

5.3 初始化数据库

./scripts/Initialize-Database.sh

脚本打印「public 表 29 张」表示结构建好。清空重建加 --reset。

5.4 构建

cd java-mosskb-ui
npm install
NODE_OPTIONS=--max_old_space_size=4096 npm run build    # 产物在 dist/ui

cd ../java-mosskb
./scripts/Start-Local.sh --build

NODE_OPTIONS 要在 Linux 上显式传：前端构建脚本里提高 Node 堆上限的写法是 Windows 的语法，在 Linux 上不生效，构建会因内存不足失败，原因见 5.8。

后端构建同样可以用 mvn clean -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dgpg.skip=true -Pproduction package，产物在 mosskb-web/target。

5.5 启动方式一：脚本启动（开发与验证）

./scripts/Start-Local.sh

默认监听 127.0.0.1。在 WSL 里部署、用 Windows 浏览器访问时，把前端监听地址改成 0.0.0.0：

FRONTEND_HOST=0.0.0.0 ./scripts/Start-Local.sh

脚本输出 UI: http://localhost:3000/ui/，后端是 10060。日志位置与 Windows 相同：mosskb-web/logs/startup.log 与 java-mosskb-ui/.local/vite.log。

5.6 启动方式二：nginx 静态站点 + 后端 JAR（正式部署）

正式环境不需要 Vite 开发服务器：把构建好的静态文件交给 nginx，反向代理把接口转给后端 JAR。

# 前端静态文件
sudo mkdir -p /opt/java-mosskb/ui
sudo cp -r java-mosskb-ui/dist/ui/. /opt/java-mosskb/ui/

# 后端 JAR 固定成一个不随版本变化的名字，方便写服务单元
sudo mkdir -p /opt/java-mosskb/app
sudo cp java-mosskb/mosskb-web/target/mosskb-web-*.jar /opt/java-mosskb/app/mosskb-web.jar
sudo cp java-mosskb/mosskb-web/my.txt java-mosskb/mosskb-web/secrets.txt /opt/java-mosskb/app/
sudo chmod 600 /opt/java-mosskb/app/my.txt /opt/java-mosskb/app/secrets.txt

# 后端运行目录里放配置，直接启动
cd /opt/java-mosskb/app
java -jar mosskb-web.jar --server.port=10060

nginx 配置 /etc/nginx/conf.d/java-mosskb.conf：

server {
  listen 80;
  server_name _;

  # 前端产物按 /ui/ 前缀访问，所以静态根目录是它的上一级
  root /opt/java-mosskb;
  index index.html;

  # 前端是单页应用，找不到的路径都回落到入口页
  location /ui/ {
    try_files $uri $uri/ /ui/index.html;
  }

  # 接口与静态资源转发给后端
  location /api/ {
    proxy_pass http://127.0.0.1:10060;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 问答接口是 SSE 流式返回，必须关闭缓冲并放宽读超时
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
  }

  location /pages/ {
    proxy_pass http://127.0.0.1:10060;
    proxy_set_header Host $host;
  }

  location /doc/ {
    proxy_pass http://127.0.0.1:10060;
    proxy_set_header Host $host;
  }

  location /static/ {
    proxy_pass http://127.0.0.1:10060;
    proxy_set_header Host $host;
  }
}

四个转发路径与前端开发服务器里的代理保持一致：/api 是接口，/pages 是知识库原文与预览，/doc 与 /static 是文档与静态资源。检查并加载配置：

sudo nginx -t
sudo systemctl reload nginx

proxy_buffering off 是流式回答能逐字显示的关键：nginx 默认会缓冲上游响应，前端要等整段回答生成完才看到内容。

配置正确时，浏览器访问 http://<服务器地址>/ui/ 就能看到与开发环境一致的界面，接口由 nginx 转发给后端：

5.7 用 systemd 托管后端

把后端做成开机自启的服务，配置文件 /etc/systemd/system/java-mosskb.service：

[Unit]
Description=Java MossKB backend
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/java-mosskb/app
ExecStart=/usr/bin/java -jar /opt/java-mosskb/app/mosskb-web.jar --server.port=10060
Restart=on-failure
RestartSec=5
Environment=LANG=C.UTF-8
User=mosskb
Group=mosskb

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now java-mosskb
sudo systemctl status java-mosskb
journalctl -u java-mosskb -f

User=mosskb 指向前一节创建的运行账号；配置文件权限已经收紧到 600，所以要让该账号拥有 my.txt 与 secrets.txt。需要隔离 Python 执行器时再按隔离 Python 执行环境配置准备 Docker 或宿主沙箱。

5.8 WSL Ubuntu 实测记录

下面这些步骤在一台干净的 WSL Ubuntu 上逐条跑过。代码复制到 Linux 文件系统（后端 14 MB、前端 107 MB），不直接使用 /mnt 下的目录，避免 node_modules 在两个系统之间互相覆盖；数据库用宿主机上已装好 pgvector 的 PostgreSQL，按 1.3 放开监听、认证与防火墙后连接。

WSL 会把 Linux 里监听 0.0.0.0 的端口映射到 Windows 的 localhost，所以从 Windows 浏览器直接访问即可。实测中踩到两件事，写在这里省得再踩一遍：

• 前端 npm run build 依赖 NODE_OPTIONS 提高 Node 堆上限，脚本里写的是 Windows 的 set NODE_OPTIONS=...，在 Linux 上不生效，构建会因内存不足直接 abort（退出码 134）。Linux 上显式传一次环境变量即可：NODE_OPTIONS=--max_old_space_size=4096 npm run build。
• npm 国内镜像偶尔缺少个别包的版本，报 404 时把源切回官方即可：npm install --registry=https://registry.npmjs.org。

前端产物不区分系统，可以在任意一台机器上构建后复制过去；如果目标机器没有 Node.js，这一步可以在构建机上完成，只把 dist/ui 拷过去。

六、验证部署

部署完成后至少验证三件事：数据库结构、后端接口、前端页面。前两项可以用下面两个小程序直接检查。

用 JDBC 核对表数量，SQL 用文本块书写：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

public class DatabaseCheck {
  public static void main(String[] args) throws Exception {
    String url = "jdbc:postgresql://127.0.0.1:5432/moss_kb";
    String sql = """
        SELECT count(*) AS table_count
        FROM information_schema.tables
        WHERE table_schema = 'public'
        """;
    try (Connection connection = DriverManager.getConnection(url, "moss_kb", "<数据库密码>");
        Statement statement = connection.createStatement();
        ResultSet resultSet = statement.executeQuery(sql)) {
      if (resultSet.next()) {
        System.out.println("public 表数量：" + resultSet.getInt("table_count"));
      }
    }
  }
}

用 JDK 自带的 HTTP 客户端调用登录接口，确认后端与数据库都通：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class LoginCheck {
  public static void main(String[] args) throws Exception {
    String body = """
        {"username":"admin","password":"<初始密码>"}
        """;
    HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("http://127.0.0.1:10060/api/user/login"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode() + " " + response.body());
  }
}

返回 200 且 data 里带令牌，说明后端已经连上数据库并能签发登录凭据。浏览器打开前端地址登录后即可看到应用、知识库与系统管理：

七、检索与多轮问答

前端提交确认后的分段时，应保留解析阶段返回的文件 id。后端先完成远程向量请求，再用事务保存文档与分段。只有成功提交后，文档状态才标为完成。

支持向量检索、关键词相似度检索和混合检索。向量检索使用余弦相似度；关键词检索使用 PostgreSQL 的文本片段相似度；混合检索将两类得分相加。已停用或已删除的文档和分段不参加检索。

多轮处理过程为：读取同一会话的持久摘要及近期问答，将省略主题的追问改写为独立检索问题。单次提问内执行“检索、证据核验、按缺口再次检索”的循环，然后把历史上下文、累计资料和当前问题交给推理模型。只有历史 token 超出预算才压缩。界面的历史轮数仅作为压缩后近期原文保留目标，不单独触发压缩。配置与接口见上下文压缩，隔离 Python 执行见隔离 Python 执行环境配置。

调试配置按会话保存，避免不同调试窗口互相覆盖。回答保存成功后才发出流结束事件，紧接着的追问可以读取上一轮回答。分享访客凭据限制在聊天相关接口，历史记录读取还会校验应用和会话归属。

原版界面已包含历史对话与问题改写处理，Java 实现也支持这条多轮检索问答路径。这里的多轮检索不等同于任意工具调用或完整工作流执行。

八、相关章节

• 数据库设计：表结构与种子数据。
• 支持自定义模型：平台接入、模型目录与自定义模型 ID。
• 多轮检索、上下文压缩：检索轮次、追问改写与 token 阈值。
• 隔离 Python 执行环境配置：Docker over TCP、宿主沙箱与边界对比。
• 离线运行向量模型：不依赖远程服务的向量方案。