WeKnora 部署文档

项目: WeKnora v0.6.2 (腾讯开源 RAG 知识库系统)

目标服务器: 10.9.205.104

部署路径: /home/chai/data/WeKnora/

部署日期: 2025-06-13

一、环境信息

项目	详情
操作系统	Anolis OS 8.6
CPU	Intel Celeron J6412 (4核, 无AVX/AVX2指令集)
内存	15GB
磁盘	/home/chai/data 分区 868GB 可用
Docker	已安装
Docker Compose	插件版本 (docker compose)

二、部署前准备

2.1 环境检测

将 check_weknora.sh 上传到服务器执行，检测 Docker、内存、磁盘、端口等 11 项指标。

2.2 Docker 镜像加速

由于国内网络环境，需配置 Docker 镜像加速器。编辑 /etc/docker/daemon.json：

{  "registry-mirrors": [    "https://mirror.ccs.tencentyun.com",    "https://docker.m.daocloud.io",    "https://docker.1ms.run"  ]}

执行 systemctl restart docker 生效。

2.3 下载源码

如果 GitHub 直连较慢，可通过代理下载：

# 方式一：直连wget https://github.com/Tencent/WeKnora/archive/refs/tags/v0.6.2.tar.gz# 方式二：通过代理wget https://proxy.1st.name/https://github.com/Tencent/WeKnora/archive/refs/tags/v0.6.2.tar.gztar -xzf v0.6.2.tar.gzmv WeKnora-0.6.2 /home/chai/data/WeKnoracd /home/chai/data/WeKnora

三、关键配置修改

3.1 环境变量 (.env)

从 .env.example 复制并修改：

cp .env.example .env

.env 核心配置：

# 运行模式GIN_MODE=releaseTZ=Asia/Shanghai# 数据库（使用内置 PostgreSQL 容器）DB_DRIVER=postgresDB_HOST=postgresDB_PORT=5432DB_USER=postgresDB_PASSWORD=weknora-postgres-2024!@#DB_NAME=WeKnora# 向量存储（使用 pgvector）RETRIEVE_DRIVER=postgres# 文件存储（本地）STORAGE_TYPE=localLOCAL_STORAGE_BASE_DIR=/data/files# 流处理后端STREAM_MANAGER_TYPE=redis# RedisREDIS_PASSWORD=weknora-redis-2024!@#REDIS_DB=0REDIS_PREFIX=stream:# Ollama 地址（如有本地模型）OLLAMA_BASE_URL=http://host.docker.internal:11434# 安全密钥TENANT_AES_KEY=weknorarag-api-key-secret-secretSYSTEM_AES_KEY=weknora-system-aes-key-32bytes!!JWT_SECRET=weknora-jwt-secret# 注册控制DISABLE_REGISTRATION=false# 知识图谱（低配机器建议关闭）ENABLE_GRAPH_RAG=false# Embedding 并发数CONCURRENCY_POOL_SIZE=5# 文件上传大小限制 (MB)# MAX_FILE_SIZE_MB=50# 前端端口FRONTEND_PORT=80# 后端端口APP_PORT=8080# Docreader 连接DOCREADER_ADDR=docreader:50051DOCREADER_TRANSPORT=grpc# APK 镜像源APK_MIRROR_ARG=mirrors.tencent.com

3.2 docker-compose.yml 修改

注意: 以下修改已针对 J6412 CPU（不支持 AVX）及数据持久化需求完成。

修改项 1：PostgreSQL 镜像替换

原镜像 paradedb/paradedb:v0.22.2-pg17 依赖 AVX 指令集，在 J6412 上会报 Illegal instruction。替换为 pgvector/pgvector:pg17：

postgres:  image: pgvector/pgvector:pg17          # 原: paradedb/paradedb:v0.22.2-pg17  container_name: WeKnora-postgres  environment:    - POSTGRES_USER=${DB_USER}    - POSTGRES_PASSWORD=${DB_PASSWORD}    - POSTGRES_DB=${DB_NAME}  volumes:    - /home/chai/data/weknora-postgres:/var/lib/postgresql/data  networks:    - WeKnora-network  healthcheck:    test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]    interval: 10s    timeout: 10s    retries: 3    start_period: 30s  restart: unless-stopped  stop_grace_period: 1m

修改项 2：数据卷改为本地路径绑定挂载

服务	挂载点	宿主机路径
postgres	/var/lib/postgresql/data	/home/chai/data/weknora-postgres
app (files)	/data/files	/home/chai/data/weknora-files
redis	/data	/home/chai/data/weknora-redis

# app 服务中的 files 卷volumes:  - /home/chai/data/weknora-files:/data/files# redis 服务新增持久化redis:  image: redis:7.0-alpine  container_name: WeKnora-redis  command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}  volumes:    - /home/chai/data/weknora-redis:/data  restart: always  networks:    - WeKnora-network

3.3 数据库迁移脚本修改

由于替换了 pgvector 镜像（不含 pg_search 扩展），需要注释所有迁移 SQL 中的 pg_search 相关语句。

在 migrations/ 目录下的 SQL 文件中，将以下语句前面加 -- 注释：

-- CREATE EXTENSION IF NOT EXISTS pg_search;-- ALTER EXTENSION pg_search UPDATE;-- DROP EXTENSION IF EXISTS pg_search;

3.4 Go 源码修改

修改 internal/repository/repository.go，将 ParadeDB 专用函数替换：

// 原代码："paradedb.score(id) as score"// 修改为："0.0 as score"

注意：此修改需要重新构建镜像，或者如果使用预构建镜像，需要在运行时通过其他方式绕过。

四、部署步骤

步骤 1：创建数据目录

mkdir -p /home/chai/data/weknora-postgresmkdir -p /home/chai/data/weknora-filesmkdir -p /home/chai/data/weknora-redis

步骤 2：配置 .env

cd /home/chai/data/WeKnoracp .env.example .env# 编辑 .env，修改 DB_PASSWORD、REDIS_PASSWORD 等关键配置

步骤 3：应用上述修改

修改 docker-compose.yml 中的镜像、卷挂载路径

注释 migrations/ 中的 pg_search 语句

修改 internal/repository/repository.go 中的 paradedb.score 调用

步骤 4：拉取镜像

cd /home/chai/data/WeKnoradocker compose pull

步骤 5：启动服务

docker compose up -d

步骤 6：验证状态

docker compose ps# 预期输出 5 个容器均为 Up 状态：# WeKnora-frontend# WeKnora-app# WeKnora-docreader# WeKnora-postgres# WeKnora-redis

五、服务端口

服务	端口	用途
Frontend (Nginx)	80	Web UI 访问入口
App (API)	8080	后端 REST API
Docreader	50051	gRPC 文档解析（仅内网）
PostgreSQL	5432	数据库（仅内网）
Redis	6379	缓存/流处理（仅内网）

访问地址

Web UI: http://10.9.205.104

API: http://10.9.205.104:8080

六、常见问题与解决

6.1 Docker 镜像拉取超时

现象: docker compose pull 时出现 dial tcp: i/o timeout

解决: 配置 registry-mirrors（见 2.2 节），重启 Docker 后重试。

6.2 PostgreSQL 启动报 Illegal instruction

现象: WeKnora-postgres 容器日志中出现 Illegal instruction (core dumped)

原因: paradedb/paradedb 镜像需要 AVX 指令集，J6412 等低端 CPU 不支持。

解决: 替换为 pgvector/pgvector:pg17 镜像（见 3.2 节修改项 1），并注释迁移脚本中的 pg_search 扩展。

6.3 磁盘空间不足

现象: 根分区空间紧张

解决: 将数据目录迁移到大容量分区：

# 停止服务docker compose down# 移动数据mv /opt/WeKnora /home/chai/data/WeKnora# 创建本地数据目录mkdir -p /home/chai/data/{weknora-postgres,weknora-files,weknora-redis}# 修改 docker-compose.yml 中的卷挂载路径# 重新启动docker compose up -d

6.4 写入 daemon.json 失败 (Windows PowerShell)

现象: 通过 PowerShell 远程执行 echo 写入 JSON 时引号转义失败

解决: 使用 base64 编码绕过：

echo '{"registry-mirrors":["https://mirror.ccs.tencentyun.com"]}' | base64 -w0# 在服务器上解码写入echo "<base64内容>" | base64 -d > /etc/docker/daemon.json

七、日常运维

查看日志

# 查看所有容器日志docker compose logs -f# 查看特定服务日志docker compose logs -f appdocker compose logs -f postgres

重启服务

cd /home/chai/data/WeKnoradocker compose restart        # 重启所有docker compose restart app    # 仅重启后端

停止服务

docker compose down

更新版本

cd /home/chai/data/WeKnoradocker compose downgit pull  # 或重新下载新版本docker compose pulldocker compose up -d

备份数据

# 备份 PostgreSQLdocker exec WeKnora-postgres pg_dump -U postgres WeKnora > weknora_backup_$(date +%Y%m%d).sql# 备份文件tar -czf weknora_files_$(date +%Y%m%d).tar.gz /home/chai/data/weknora-files/# 备份 Redis (AOF 已自动持久化)cp -r /home/chai/data/weknora-redis/ weknora_redis_backup_$(date +%Y%m%d)/

八、服务器连接方式

通过 SSH 密钥连接：

# Windows PowerShellssh -i "$env:USERPROFILE\.ssh\weknora_deploy" root@10.9.205.104