跳到主要内容

WeKnora 部署踩坑记录

项目地址​

https://github.com/Tencent/WeKnora

部署方式​

使用 Docker 部署：

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env  # 按需编辑配置
docker compose up -d  # 启动核心服务

注意事项​

1. 快速启动用 .env.lite.example​

如果想快速启动，使用 .env.lite.example 而不是 .env.example。 它会使用本地 SQLite 文件以及内存作为运行基础，无需额外依赖数据库服务。

2. Frontend 需要先构建​

Frontend 的 Dockerfile 只是用 Nginx 挂载 dist，不会自动构建。 必须先构建出 dist 目录，否则 frontend 容器启动不起来。

官方在 docker-compose.yml 中的注释：

#Requires frontend/dist — run ./scripts/build_frontend_dist.sh before --build

构建步骤：

# 1. 执行官方脚本构建 dist
cd frontend
./scripts/build_frontend_dist.sh

# 或者直接构建 Docker 镜像
docker build -t weknora-ui:2026.06.26 .

3. ParadeDB 在老机器上可能启动失败​

如果使用 ParadeDB 作为向量数据库，在老机器上可能会遇到以下错误：

Illegal instruction (core dumped)
child process exited with exit code 132

这是典型的 CPU 指令集不兼容错误。PostgreSQL 在初始化时执行了当前 CPU 不支持的指令。 ParadeDB 是针对较新 CPU 优化的构建，在老旧 CPU（如不支持 AVX2 等指令集的型号）上会崩溃。

解决方案：

  • 方案一：更换机器或使用支持所需指令集的 CPU
  • 方案二：使用 .env.lite.example（SQLite + in-memory）避免 ParadeDB 依赖
  • 方案三：修改配置，使用其他兼容的向量数据库后端

4. App 和 docreader 需要单独构建​

直接运行 docker compose up -d 会自动执行 app 和 docreader 的 build，但大概率会失败，原因有二：

  1. 科学上网问题：构建过程中需要拉取依赖，可能需要代理环境
  2. App 使用 Go 编译：需要设置国内 GOPROXY

App 构建命令（需指定 GOPROXY）：

docker build --build-arg GOPROXY_ARG=https://goproxy.cn,direct -t weknora-app:2026.06.26 -f ./docker/Dockerfile.app .

Docreader 构建命令：

docker build -t weknora-docreader:2026.06.26 -f ./docker/Dockerfile.docreader .

5. 将源码中的 config 和 skills 目录拷贝到部署目录​

在服务器上部署时，需要修改 docker-compose.yml：

  1. 注释掉 frontend、app、docreader 的 build 块
  2. 将 image 指向之前构建好的镜像

但只改 compose.yml 还不够，还需要将源码中的 config 和 skills 目录拷贝到部署目录。

因为 app 服务中有以下 volumes 挂载：

volumes:
  - data-files:/data/files
  - docreader-tmp:/tmp/docreader:ro
  - ./config/config.yaml:/app/config/config.yaml    # 需要 config 目录
  - ./skills/preloaded:/app/skills/preloaded         # 需要 skills 目录

如果不拷贝 config 和 skills 目录，容器启动时会因找不到挂载源而报错。

6. 注册后应关闭新用户注册​

WeKnora 没有预设管理员的概念，每个人注册后都会成为管理员，可以新增成员。 如果只是自用，注册好自己的账号后，建议关闭新用户注册。

在 .env 中将以下配置设为 true：

DISABLE_REGISTRATION=true

注意： 修改 .env 后，仅重启容器不生效，需要删除容器再重新启动。

部署步骤总结​

  1. 构建三个镜像：weknora-app、weknora-docreader、weknora-ui
  2. 拷贝源码中的 config/ 和 skills/ 目录到服务器部署目录
  3. 去掉 docker-compose.yml 中的 build 块，填写已有 image 名称
  4. 配置好 .env 文件（包括设置 DISABLE_REGISTRATION=true）
  5. 运行 docker compose up -d
  6. 注册账号后，如需关闭注册，修改 DISABLE_REGISTRATION=true，删容器重新启动