安装部署

服务器要求

项目	要求
系统与架构	Linux，x86_64（镜像只发布 linux/amd64）
Docker	Docker 24 以上，Docker Compose v2.24 以上
配置	4 核 8 GB 起步。空载时全部服务约占 1.7 GB 内存；每个进行中的对话会起一个沙箱容器；知识库越大，向量库占得越多
磁盘	镜像约 6 GB（开多跳检索再多一些），另按文档量留足
网络	能访问镜像仓库 `crpi-6q638zy09wmnj70w.cn-hangzhou.personal.cr.aliyuncs.com`，能访问模型服务与 MinerU

另外准备两样 KnowWork 不自带的服务：

模型服务：OpenAI 兼容接口。至少一个对话模型；用知识库还要一个向量模型；重排序模型可选。
MinerU：解析 PDF、Word、PPT。

你会拿到

交付物	用途
授权文件 `*.license`	开通商业版功能，有效期写在里面
镜像仓库的只读账号	拉取商业版镜像
交付包 `know_work_<版本>_<日期>.tar.gz`	全部部署文件，解压就能装；可选服务的编排也在里面
本版本的更新说明	升级时看要注意什么

安装

tar -xzf know_work_v0.0.3_20261028.tar.gz && cd know_work_v0.0.3_20261028
cp /path/to/xxx.license license/          # 目录里只放一份授权
docker login crpi-6q638zy09wmnj70w.cn-hangzhou.personal.cr.aliyuncs.com
./install-pro.sh

脚本会检查 Docker 版本和授权、第一次运行时生成 .env、拉镜像（失败自动重试）、启动全部服务，并一直等到打印「KnowWork 已就绪」和访问地址。

常用参数：

参数	作用
`--url http://公网IP:8080`	指定浏览器访问的外部地址
`--sag`	同时部署多跳检索，见可选服务
`--no-sandbox`	不启用会话沙箱（不推荐，见下文）
`--no-pull`	不拉镜像，用本机已有的（离线部署）
`--timeout 600`	等待就绪的秒数
`--pro-registry <地址>`	换镜像仓库地址，例如阿里云 VPC 内网地址

保管好 .env

第一次运行会在部署目录里生成 .env，里面是访问地址和各项凭证。不要删除，也不要提交到任何代码仓库。部署主密钥等存放在 Docker 卷里，备份时要一起备份，见升级与备份。

包含哪些服务

服务	作用
gateway	网页与接口的统一入口，对外端口默认 8080
api	业务服务：账号权限、对话、模型调用、知识库；启动时自动升级数据库
worker	后台任务：文档解析、嵌入、自动抽取等
runtime-host	智能体运行时
postgres、redis、rustfs	数据库、缓存与队列、文件存储
milvus、etcd	知识库的向量检索

会话沙箱容器按对话自动创建，空闲一段时间后自动回收，不在上表里。

访问地址

.env 里有两项要和实际访问方式一致：

KNOWWORK_PUBLIC_BASE_URL：浏览器访问的外部地址，邀请链接和单点登录回调都用它拼；
KNOWWORK_COOKIE_SECURE：会话 Cookie 是否只走 HTTPS。用 http 访问时必须是 false，否则登录后又会回到登录页。

云服务器的公网 IP 一般不在网卡上，脚本取到的是内网地址。用 ./install-pro.sh --url http://公网IP:8080 再跑一次，并在安全组里放行 8080 端口。

上 HTTPS：在网关前面放一层你们自己的反向代理或负载均衡做 TLS 终止，转发到 8080；然后把访问地址改成 https://…、KNOWWORK_COOKIE_SECURE 改成 true，在部署目录里执行 docker compose up -d 生效。

改端口、只在本机访问：改 .env 里的 KNOWWORK_PORT（默认 8080）、KNOWWORK_BIND_ADDRESS（只想本机访问时改成 127.0.0.1）。

单点登录（OIDC）

接入公司已有的身份系统（Keycloak、Authing、Azure AD、Okta 等支持 OIDC 的都可以）：在 .env 里填

KNOWWORK_OIDC_ISSUER=https://你的身份系统/realms/xxx
KNOWWORK_OIDC_CLIENT_ID=knowwork
KNOWWORK_OIDC_CLIENT_SECRET=<在身份系统里生成>
KNOWWORK_OIDC_REDIRECT_URI=<访问地址>/api/auth/oidc/callback

执行 docker compose up -d 后，登录页多一个企业账号入口。第一次用单点登录进来的员工自动建账号，以「成员」身份进默认空间。

会话沙箱

默认打开。每个对话有一个独立的 Docker 容器，智能助手执行的命令、读写的文件都在容器里，碰不到服务器本身和别人的数据。沙箱容器去掉了全部 Linux 能力、禁止提权。

配置项	默认	说明
`KNOWWORK_SANDBOX_ALLOW_INTERNET`	`true`	设成 `false` 时沙箱完全断网
`KNOWWORK_SANDBOX_RUNTIME`	空	可选的容器运行时，例如已安装的 `runsc`（gVisor），隔离更强

不需要沙箱时可以用 --no-sandbox 安装，代价是：智能助手不能执行命令，生成不了 Word 和 Excel，知识库的 PPT 预览和表格公式重算也用不了。

离线部署

在能联网的机器上拉好全部镜像（部署目录里执行 docker compose config --images 能列出来）并 docker save 导出，拷到目标机器 docker load 导入，然后在 .env 里设 KNOWWORK_PULL_POLICY=never，执行 ./install-pro.sh --no-pull。

检查运行状态

docker compose ps                         # 各服务状态
docker compose logs api worker            # 业务服务与后台任务的日志
curl http://127.0.0.1:8080/ready          # 数据库与运行时是否正常

用系统管理员登录后，「管理后台」→「系统设置」里能看到版本、授权是否有效与到期时间；「运行面板」里能看到后台任务的排队与执行情况。

服务器要求​

你会拿到​

安装​

包含哪些服务​

访问地址​

单点登录（OIDC）​

会话沙箱​

离线部署​

检查运行状态​