KnowForge 安装指南

KnowForge 编译为单个二进制文件，内嵌 Next.js SSR 与 Node.js 24 运行时，默认零配置使用 SQLite，启动后通过图形化安装向导完成初始化。本文覆盖四种安装方式：Docker（推荐）、二进制发布包、源码构建、开发模式，以及生产环境的 Nginx / systemd 配置。

环境要求

项目	要求
操作系统	Linux（amd64 / arm64）、macOS、Windows
内存	≥ 512 MB（内嵌 Node.js SSR 运行时）
磁盘	≥ 200 MB + 数据空间（数据库与上传文件）
端口	默认 `6969`，对外提供服务

Docker 方式：Docker 20+ 与 Docker Compose v2，无其他依赖
二进制方式：无任何运行时依赖（Node.js 已内嵌）
源码构建：Go 1.25+、Node.js 24.20.0（精确版本，构建脚本会校验）、pnpm 9、make

方式一：Docker Compose（推荐）

默认使用零配置 SQLite，数据（数据库、上传文件、配置）持久化在命名卷 knowforge-data。

git clone https://github.com/devlive-community/knowforge.git
cd knowforge
docker compose up -d

查看日志确认启动完成：

docker compose logs -f knowforge

浏览器访问 http://<主机IP>:6969/install 完成初始化（见安装向导）。

使用官方预构建镜像：编辑 docker-compose.yml，删除 build: 段并将 image: 改为：

    image: ghcr.io/devlive-community/knowforge:latest

方式二：Docker 单容器

docker run -d \
  --name knowforge \
  --restart unless-stopped \
  -p 6969:6969 \
  -v knowforge-data:/data \
  ghcr.io/devlive-community/knowforge:latest

数据全部落在 /data 卷中；升级时拉取新镜像重建容器即可，数据不丢失。

方式三：二进制发布包

从 Releases 下载对应平台的压缩包（knowforge-server-linux-amd64 / arm64 / macOS / Windows），解压后直接运行：

chmod +x knowforge-server
./knowforge-server -port 6969

默认数据目录为当前目录下的 ./data，通过环境变量 KNOWFORGE_DATA 指定持久化路径：

KNOWFORGE_DATA=/var/lib/knowforge ./knowforge-server -port 6969

方式四：源码构建

源码构建会将 Next.js SSR 产物与 Node.js 24 运行时打包进单个 Go 二进制。

git clone https://github.com/devlive-community/knowforge.git
cd knowforge

# 1. 安装前端依赖（要求 Node.js 24.20.0）
make web-install

# 2. 构建本机平台的单个二进制
make build

产物为 bin/knowforge-server。交叉编译 Linux amd64 发布包用 make release-linux。

启动：

KNOWFORGE_DATA=./data ./bin/knowforge-server -port 6969

初始化安装向导

首次启动后访问 http://<主机>:6969/install，向导分两步：

数据库配置
- SQLite（默认）：零配置，指定数据库文件路径（留空使用默认 data/knowforge.db）
- MySQL / PostgreSQL：填写主机、端口、库名、用户名、密码
管理员账户：设置管理员用户名、邮箱与密码（密码至少 6 位）

完成后自动跳转登录页。用刚才创建的管理员账户登录，即可进入管理后台进行站点设置（站点名称、Logo、站点访问地址等）、邮件服务（SMTP）与用户管理等配置。

安装向导只在系统未初始化时可用；重复访问 /install 会跳转到首页。

配置项参考

配置通过环境变量注入，持久化配置保存在数据目录的 config.json。

环境变量	默认值	说明
`KNOWFORGE_DATA`	`./data`	数据目录（数据库、上传文件、config.json）
`KNOWFORGE_PORT`	`6969`	服务监听端口（也可用 `-port` 参数）
`KNOWFORGE_WEB_PORT`	`6900`	内嵌 Next.js SSR 内部端口，一般无需配置
`KNOWFORGE_TRUSTED_PROXIES`	空	受信任反向代理 IP 列表（逗号分隔），用于解析真实客户端 IP；本机 nginx 填 `127.0.0.1,::1`
`KNOWFORGE_SITE_URL`	空	站点对外地址（如 `https://kb.example.com`），用于邮件链接与 sitemap 生成；nginx 已设置 `X-Forwarded-Host` 时可不配
`KNOWFORGE_STATIC_ROOT`	内置	Next.js 静态资源目录；跨版本部署时指向共享目录可避免旧页面 404
`KNOWFORGE_UPGRADE`	空	在线升级开关，设为 `enabled` 启用
`KNOWFORGE_UPSTREAM_REPO`	`devlive-community/knowforge`	在线升级源仓库

数据目录结构：

data/
├── config.json        # 持久化配置（数据库、密钥等）
├── knowforge.db      # SQLite 数据库（使用 SQLite 时）
├── uploads/           # 上传文件
└── sitemaps/          # 后台定时生成的 sitemap 静态文件

数据库切换

安装向导中可直接选择 SQLite / MySQL / PostgreSQL。三种数据库均由 GORM 支持自动迁移，无需手工建表。

MySQL 连接示例（安装向导中填写）：

字段	示例值
主机	`127.0.0.1`
端口	`3306`
数据库	`knowforge`
用户名 / 密码	自行创建

PostgreSQL：端口默认 5432，其余同理。

建议提前在数据库中创建库并授权：CREATE DATABASE knowforge CHARACTER SET utf8mb4;（MySQL）或 CREATE DATABASE knowforge;（PostgreSQL）。

备份与恢复

备份：管理后台「系统设置 · 备份」可以立即备份，也可以设置每天或每周的自动备份（按服务器时区的整点执行，自动备份保留最近若干份，手动备份不会被自动删除）。备份文件为 .zip，保存在数据目录的 backups/ 下，包含：

数据库中全部业务数据（各表逐行导出为 JSON，与数据库类型无关）；搜索索引、限流计数、验证码、登录挑战、后台任务队列等运行时数据不包含，恢复后自动重建；
可选：本地上传目录 uploads/ 中的文件。使用对象存储时文件在对象存储中，不在备份里；
站点密钥（恢复后原有登录状态保持有效）。

备份文件包含站点密钥、密码哈希与各类接口密钥，请妥善保管。下载备份需要管理员权限；开启了二次认证并勾选「导出数据」时需先验证。备份不会上传到用于公开访问的对象存储。

恢复：在新服务器上部署同一版本或更新版本的 KnowForge，打开安装向导并选择「从备份恢复」：

设置数据库：必须是空数据库，可以与备份时不同（例如从 SQLite 换成 PostgreSQL，恢复即完成数据迁移）；
上传备份文件，向导显示建表、写入数据、恢复文件的进度；
完成后用备份中的账号登录。

备份不能来自比当前更新的版本。插件运行时（如 PDF 导出所用的浏览器）不在备份中，恢复后在「插件」中重新安装即可。

运行指标（Prometheus）

管理后台「系统设置 · 运行指标」开启后，GET /metrics 以 Prometheus 文本格式输出运行指标，抓取时需在请求头携带访问令牌（开启时生成，只显示一次，可重新生成；未开启时返回 404）：

scrape_configs:
  - job_name: knowforge
    scheme: https
    metrics_path: /metrics
    authorization:
      credentials: <访问令牌>
    static_configs:
      - targets: ['kb.example.com']

主要指标：

指标	说明
`knowforge_http_requests_total{method,route,status}`	请求数（路由为路径模板，如 `/api/v1/books/:id`；页面请求为 `web`）
`knowforge_http_request_duration_seconds`	请求耗时直方图（不含事件流）
`knowforge_http_requests_in_flight`	正在处理的请求数
`knowforge_sse_connections{route}`	打开中的事件流连接数
`knowforge_ai_calls_total{feature,kind,model,status}` / `knowforge_ai_tokens_total{kind,direction}` / `knowforge_ai_cost_total{currency}` / `knowforge_ai_call_duration_seconds`	模型调用次数、tokens、估算费用与耗时
`knowforge_jobs{type,status}` / `knowforge_jobs_oldest_waiting_seconds`	后台任务积压（不含已成功的）与最早一个待执行任务的等待时长
`knowforge_cluster_instances`	在线实例数
`knowforge_db_connections{state}` / `knowforge_db_wait_total` / `knowforge_db_wait_seconds_total`	数据库连接池
`knowforge_users` / `knowforge_books` / `knowforge_documents`	数据总量（每分钟更新）
`knowforge_build_info{version,go_version}`、`go_goroutines`、`go_memstats_*`	版本与运行时

多实例部署时请逐个实例抓取：请求、事件流与模型调用是各实例自己的计数；任务积压、在线实例与数据总量来自数据库，各实例相同。

生产部署（systemd + Nginx + TLS）

参考 deploy/ 目录下的示例文件。

1. systemd 服务

# 放置二进制
sudo mkdir -p /var/www/knowforge/current
sudo cp bin/knowforge-server /var/www/knowforge/current/

# 环境变量文件
sudo mkdir -p /etc/knowforge
sudo cp deploy/knowforge.env.example /etc/knowforge/knowforge.env
sudo nano /etc/knowforge/knowforge.env   # 按需修改

# 数据目录授权（服务以 www-data 运行）
sudo mkdir -p /var/lib/knowforge
sudo chown www-data:www-data /var/lib/knowforge

# 注册服务
sudo cp deploy/knowforge-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now knowforge

2. Nginx 反向代理

sudo cp deploy/nginx.conf.example /etc/nginx/sites-available/knowforge
sudo ln -s /etc/nginx/sites-available/knowforge /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

3. TLS 证书

DNS 解析指向服务器后，用 certbot 一键签发并配置 80→443 跳转：

sudo certbot --nginx -d kb.example.com

证书自动续期由 certbot.timer 负责。

4. 后台站点设置

登录管理后台完成两件事，否则部分功能不完整：

站点设置：填写「站点访问地址」（https://kb.example.com）——邮件中的链接与每日自动生成的 sitemap.xml 都依赖它
邮件服务：配置 SMTP 发信地址、端口、账号与密码（用于注册验证、密码重置等邮件）

多实例部署

访问量较大或需要高可用时，可以在负载均衡后运行多个 KnowForge 服务实例。各实例通过共享数据库自动协作：

站内通知、问答、写作助手、整本翻译、章节导读、审核队列、插件安装日志等实时推送，送达连在任何实例上的页面；
问答、写作助手、整本翻译等后台任务可从任何实例取消或暂停；中途打开的页面会从执行任务的实例补齐已生成的内容；
后台任务队列由所有实例共同处理，长任务有心跳，只有执行它的实例退出后才会由其他实例接手；
周期巡检（到期提醒、索引补建、中断任务处理等）只由一个实例执行，该实例下线后由其他实例接手；
插件启用/禁用后所有实例同步权限，缺少插件文件（如 PDF 导出组件）的实例会自动补齐。

部署要求：

要求	说明
数据库	PostgreSQL 或 MySQL（SQLite 不支持多个服务同时写入）
数据目录	所有实例挂载同一个共享存储卷（NFS、云盘文件存储等）作为数据目录，保存上传文件、导出结果、导入源文件与插件文件；上传也可在后台改用对象存储
配置	所有实例使用相同的 `config.json`（同一数据库与 `secret`），否则登录状态与事件流凭证无法互认
负载均衡	不需要会话保持；事件流（SSE）连接可落在任意实例。代理需允许长连接：Nginx 默认遵循服务端返回的 `X-Accel-Buffering: no` 关闭缓冲，读超时需大于 25 秒的心跳间隔（默认 60 秒即可）
升级	后台的「在线升级」只会升级处理该请求的实例；多实例请用镜像或发布流程逐台升级，保持各实例版本一致

Nginx 负载均衡示例：

upstream knowforge {
    server 10.0.0.11:6969;
    server 10.0.0.12:6969;
}
server {
    # …其余配置同单实例示例，把 proxy_pass 改为 http://knowforge
    location / {
        proxy_pass http://knowforge;
        proxy_http_version 1.1;
        proxy_read_timeout 120s;
        # …proxy_set_header 同单实例示例
    }
}

部署后在管理后台「系统概览 → 服务实例」查看在线实例；数据库不支持、数据目录未共享或版本不一致时会给出提示。

升级

Docker：docker compose pull && docker compose up -d，数据在卷中不受影响
在线升级（需 KNOWFORGE_UPGRADE=enabled）：管理后台一键升级，自动下载校验、替换二进制、重启服务，失败自动回滚
二进制：下载新版本替换 knowforge-server 后 sudo systemctl restart knowforge
数据库迁移：升级后首次启动自动执行，无需手工操作

故障排查

现象	排查方向
访问 `/install` 跳转首页	系统已初始化过；如需重装，清空数据目录（会丢失全部数据）
端口被占用	`KNOWFORGE_PORT` 或 `-port` 参数换端口
sitemap.xml 返回 404	未在「站点设置」配置站点访问地址，或后台任务尚未运行（每日一次；保存站点地址后会立即触发）
nginx 后客户端 IP 显示异常	设置 `KNOWFORGE_TRUSTED_PROXIES=127.0.0.1,::1`
上传大文件失败	检查 nginx `client_max_body_size`（示例配置为 12m）
容器健康检查失败	`docker compose logs knowforge` 查看启动日志；首次启动需等待约 40 秒
升级后旧页面静态资源 404	配置 `KNOWFORGE_STATIC_ROOT` 指向跨版本共享的静态目录（见 `deploy/nginx.conf.example`）

开发模式

前后端分离运行，代码改动即时生效：

# 终端 1：Go API（数据落在 ./data）
make dev-server

# 终端 2：Next.js 前端（连接本机 API）
make dev-web

前端开发服务地址 http://localhost:3000，API 直连 http://localhost:6969。

在 PostgreSQL / MySQL 上运行后端测试

后端测试默认使用 SQLite。设置 KNOWFORGE_TEST_DB 后，同一套测试会在 PostgreSQL 或 MySQL 上运行：每个测试新建一个独立的库，结束后删除，账号需要有建库、删库权限。CI 会在三种数据库上各跑一遍。

docker run -d --rm --name kf-test-pg -e POSTGRES_PASSWORD=kftest -p 127.0.0.1:55432:5432 postgres:16-alpine
cd server && KNOWFORGE_TEST_DB=postgres KNOWFORGE_TEST_DB_PORT=55432 KNOWFORGE_TEST_DB_PASSWORD=kftest go test -p 4 ./...

docker run -d --rm --name kf-test-mysql -e MYSQL_ROOT_PASSWORD=kftest -p 127.0.0.1:53306:3306 mysql:8.4
cd server && KNOWFORGE_TEST_DB=mysql KNOWFORGE_TEST_DB_PORT=53306 KNOWFORGE_TEST_DB_PASSWORD=kftest go test -p 4 ./...

可用的环境变量：KNOWFORGE_TEST_DB（postgres / mysql）、KNOWFORGE_TEST_DB_HOST、KNOWFORGE_TEST_DB_PORT、KNOWFORGE_TEST_DB_USER（默认 postgres / root）、KNOWFORGE_TEST_DB_PASSWORD。

端到端测试

app/web/e2e 下的 Playwright 测试会自动启动一个全新的后端（端口 6989，独立数据目录）、假 AI 服务（6990）与前端开发服务（3100），与本地开发服务互不影响；覆盖会员购买与优惠券、礼品卡、试用、邀请奖励、退款、付费墙与问答实时推送。

cd app/web
pnpm exec playwright install chromium   # 首次运行需要下载测试浏览器
pnpm e2e

失败时截图与操作记录保存在 app/web/test-results/，可用 pnpm exec playwright show-trace <trace.zip> 查看。

Navigation Menu

Repository navigation

install.md

install.md

KnowForge 安装指南

目录

环境要求

方式一：Docker Compose（推荐）

方式二：Docker 单容器

方式三：二进制发布包

方式四：源码构建

初始化安装向导

配置项参考

数据库切换

备份与恢复

运行指标（Prometheus）

生产部署（systemd + Nginx + TLS）

1. systemd 服务

2. Nginx 反向代理

3. TLS 证书

4. 后台站点设置

多实例部署

升级

故障排查

开发模式

在 PostgreSQL / MySQL 上运行后端测试

端到端测试

相关链接

FilesExpand file tree

install.md

Latest commit

History

install.md

File metadata and controls

KnowForge 安装指南

目录

环境要求

方式一：Docker Compose（推荐）

方式二：Docker 单容器

方式三：二进制发布包

方式四：源码构建

初始化安装向导

配置项参考

数据库切换

备份与恢复

运行指标（Prometheus）

生产部署（systemd + Nginx + TLS）

1. systemd 服务

2. Nginx 反向代理

3. TLS 证书

4. 后台站点设置

多实例部署

升级

故障排查

开发模式

在 PostgreSQL / MySQL 上运行后端测试

端到端测试

相关链接