Docker 企业知识库搭建｜生产环境实测

在企业数字化建设过程中，知识库已经不再只是“文档存放处”，而是研发、运维、产品、售前、客服、人事等多个团队协作的核心基础设施。一个稳定、易维护、可权限控制、可备份恢复的企业知识库，能够显著降低信息传递成本，减少重复沟通，提高新人 onboarding 效率，也能沉淀项目经验、故障复盘、接口规范、运维手册和业务流程。

本文将结合生产环境实测经验，介绍如何基于 Docker 搭建一套企业级知识库系统。文章重点不只是“能跑起来”，而是围绕生产环境真正关心的问题展开，包括选型思路、服务器规划、Docker Compose 部署、反向代理、HTTPS、数据持久化、备份恢复、权限管理、升级策略、监控与常见问题处理。

本文适合对象：运维工程师、后端开发、DevOps 工程师、技术负责人，以及希望在企业内部快速落地知识库平台的团队。

一、为什么选择 Docker 搭建企业知识库？

传统部署方式通常需要手动安装运行环境，例如 Node.js、Java、PHP、Python、数据库、Redis、Nginx 等组件。随着系统复杂度提升，环境差异、依赖冲突、版本升级等问题会变得越来越明显。

Docker 的优势在企业知识库场景中非常突出：

1. 部署标准化

通过镜像和 docker-compose.yml，可以将应用、数据库、缓存、反向代理等组件统一编排。无论是在测试环境、预生产环境还是生产环境，只要 Docker 版本兼容，就可以保持一致的部署体验。

2. 迁移成本低

企业知识库最重要的是数据。采用 Docker 部署后，只需要备份数据库、上传文件目录、配置文件和 Compose 文件，就可以在另一台服务器上快速恢复。

3. 便于版本控制

部署文件可以纳入 Git 管理，每一次配置变更都有记录，方便回滚和审计。

4. 资源隔离清晰

数据库、应用、缓存、搜索组件之间相互隔离，减少环境污染。出现问题时，也可以通过容器日志快速定位。

5. 适合中小团队快速落地

对于大多数中小企业而言，知识库系统并不需要一开始就上 Kubernetes。Docker Compose 已经足以支撑相当规模的内部知识库应用。

二、知识库系统选型建议

企业知识库的选型要结合团队规模、权限要求、部署复杂度、文档类型、搜索体验和二次开发能力综合判断。

常见选择包括：

本文以 Wiki.js + PostgreSQL + Nginx Proxy Manager 为例进行说明。原因如下：

• 支持 Docker 官方化部署；
• 支持 Markdown，适合技术团队；
• 支持本地认证、LDAP、OAuth 等多种认证方式；
• 权限模型较灵活；
• UI 现代，搜索体验较好；
• 数据库采用 PostgreSQL，稳定可靠；
• 适合私有化部署与企业内部长期维护。

当然，如果你的团队更偏向结构化手册管理，BookStack 也是非常不错的选择。本文的生产环境思路同样适用于其他知识库系统。

三、生产环境服务器规划

在生产环境部署知识库之前，不建议直接“找台机器跑起来就用”。至少需要考虑资源、磁盘、网络、安全和备份。

1. 推荐服务器配置

对于 50～300 人规模的企业内部知识库，推荐配置如下：

如果文档中包含大量图片、附件、PDF、视频等内容，磁盘容量需要额外规划。知识库系统本身占用并不大，真正增长最快的是附件和数据库。

2. 磁盘目录规划

建议不要把数据随意放在用户家目录下，而是统一放在 /data 或 /opt 目录中，例如：

/data/wiki
├── docker-compose.yml
├── postgres
│   └── data
├── wikijs
│   └── data
├── nginx-proxy-manager
│   ├── data
│   └── letsencrypt
└── backup

这样做的好处是：

• 数据路径清晰；
• 方便统一备份；
• 迁移时不容易遗漏；
• 运维人员容易接手。

四、安装 Docker 与 Docker Compose

以下以 Ubuntu Server 为例。

1. 更新系统

sudo apt update
sudo apt upgrade -y

2. 安装基础依赖

sudo apt install -y ca-certificates curl gnupg lsb-release

3. 安装 Docker

可以使用 Docker 官方安装脚本：

curl -fsSL https://get.docker.com | bash

安装完成后查看版本：

docker version

4. 启用 Docker 开机自启

sudo systemctl enable docker
sudo systemctl start docker

5. 验证 Compose 插件

docker compose version

如果能正常输出版本号，说明 Docker Compose 已可使用。

五、使用 Docker Compose 部署 Wiki.js

创建项目目录：

sudo mkdir -p /data/wiki
cd /data/wiki

创建数据库目录：

sudo mkdir -p /data/wiki/postgres/data

编写 docker-compose.yml：

services:
  postgres:
    image: postgres:15
    container_name: wikijs-postgres
    restart: always
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: change_this_strong_password
      TZ: Asia/Shanghai
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    networks:
      - wiki-net

  wikijs:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs-app
    restart: always
    depends_on:
      - postgres
    environment:
      DB_TYPE: postgres
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: change_this_strong_password
      DB_NAME: wiki
      TZ: Asia/Shanghai
    ports:
      - "3000:3000"
    networks:
      - wiki-net

networks:
  wiki-net:
    driver: bridge

启动服务：

docker compose up -d

查看容器状态：

docker ps

查看日志：

docker logs -f wikijs-app

如果启动成功，访问：

http://服务器IP:3000

首次访问会进入初始化页面，创建管理员账号、设置站点名称和基础参数。

六、配置反向代理与 HTTPS

生产环境不建议直接暴露 3000 端口给用户访问，推荐通过 Nginx 或 Nginx Proxy Manager 进行反向代理，并配置 HTTPS。

1. 为什么要使用反向代理？

反向代理可以带来以下好处：

• 使用标准 80/443 端口访问；
• 配置 HTTPS 证书；
• 隐藏后端应用端口；
• 支持访问日志；
• 可以统一管理多个内部系统；
• 后续可接入 WAF、限流、认证网关等能力。

2. 使用 Nginx Proxy Manager

为了降低维护成本，可以使用 Nginx Proxy Manager，它提供图形化界面，适合中小团队管理多个内部服务。

在 /data/wiki/docker-compose.yml 中增加如下服务：

  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    restart: always
    ports:
      - "80:80"
      - "81:81"
      - "443:443"
    volumes:
      - ./nginx-proxy-manager/data:/data
      - ./nginx-proxy-manager/letsencrypt:/etc/letsencrypt
    networks:
      - wiki-net

完整启动后访问：

http://服务器IP:81

默认账号通常为：

Email: admin@example.com
Password: changeme

首次登录后务必立刻修改管理员邮箱和密码。

3. 添加代理主机

在 Nginx Proxy Manager 中添加 Proxy Host：

• Domain Names：wiki.example.com
• Scheme：http
• Forward Hostname/IP：wikijs
• Forward Port：3000
• Websockets Support：开启
• Block Common Exploits：开启

如果服务器可以被公网访问，并且域名已正确解析到服务器，可以在 SSL 页面申请 Let’s Encrypt 证书，勾选：

• Force SSL
• HTTP/2 Support

配置完成后，即可通过：

https://wiki.example.com

访问企业知识库。

七、生产环境安全加固

知识库往往包含企业内部资料、接口文档、服务器信息、客户资料甚至故障处理记录，因此安全配置非常重要。

1. 修改默认密码

包括：

• Wiki.js 管理员密码；
• PostgreSQL 数据库密码；
• Nginx Proxy Manager 默认密码；
• 服务器 SSH 密码或密钥；
• 其他中间件账号。

密码建议长度不少于 16 位，并包含大小写字母、数字和特殊字符。

2. 限制端口暴露

生产环境建议只暴露：

• 80；
• 443；
• 必要情况下开放 SSH 端口。

Wiki.js 的 3000 端口可以只在 Docker 内部网络访问。如果使用 Nginx Proxy Manager 和 Wiki.js 在同一个 Docker 网络中，甚至可以去掉 Wiki.js 的端口映射：

# ports:
#   - "3000:3000"

这样外部无法直接访问应用端口，只能通过反向代理访问。

3. 配置防火墙

以 UFW 为例：

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

如果 SSH 已经改为非 22 端口，需要按实际端口放行。

4. 启用双因素认证

如果知识库支持 MFA 或通过企业统一身份认证接入，建议开启双因素认证。特别是当知识库暴露在公网时，这一点非常重要。

5. 接入 LDAP / OAuth

企业内部如果已有统一认证系统，例如 LDAP、AD、Keycloak、GitLab、Azure AD、飞书、钉钉等，可以考虑接入统一登录。这样能够减少账号管理成本，也方便员工离职后的权限回收。

八、权限模型设计

知识库不是所有内容都应该对所有人开放。生产环境中，权限设计是非常关键的一环。

1. 按部门划分空间

可以按照以下方式规划：

公司制度
研发中心
产品中心
运维中心
测试中心
售前方案
客户支持
项目交付
故障复盘

不同空间设置不同读写权限。例如：

• 公司制度：全员可读，人事可写；
• 研发文档：研发可读写，其他部门只读或不可见；
• 运维手册：运维可写，研发只读，其他部门不可见；
• 客户资料：仅项目组成员可见；
• 故障复盘：技术团队可见，敏感内容限制访问。

2. 最小权限原则

不要为了方便直接给所有人管理员权限。建议按角色划分：

3. 建立文档负责人机制

权限只解决“谁能看、谁能改”，但不能保证文档长期有效。因此建议每个重要栏目设置负责人，定期检查内容是否过期。

例如：

• API 文档负责人：后端组长；
• 运维手册负责人：运维主管；
• 产品说明负责人：产品经理；
• 入职指南负责人：HR；
• 故障复盘负责人：SRE 团队。

九、数据持久化与备份方案

生产环境中，最不能忽视的就是备份。很多团队搭建知识库时只关注部署，直到服务器磁盘损坏、误删数据、升级失败时才发现没有可用备份。

1. 需要备份哪些内容？

至少包括：

• PostgreSQL 数据库；
• Wiki.js 上传的附件；
• Docker Compose 文件；
• Nginx Proxy Manager 配置；
• SSL 证书；
• 环境变量和密码配置；
• 备份脚本本身。

如果只备份数据库，可能会丢失图片和附件。如果只备份文件目录，可能无法恢复文档结构和版本记录。

2. PostgreSQL 备份脚本

创建备份目录：

mkdir -p /data/wiki/backup

编写备份脚本 /data/wiki/backup/backup.sh：

#!/bin/bash

BACKUP_DIR="/data/wiki/backup"
DATE=$(date +%F_%H-%M-%S)
DB_CONTAINER="wikijs-postgres"
DB_USER="wikijs"
DB_NAME="wiki"

mkdir -p ${BACKUP_DIR}/${DATE}

docker exec ${DB_CONTAINER} pg_dump -U ${DB_USER} ${DB_NAME} > ${BACKUP_DIR}/${DATE}/wiki.sql

tar -czf ${BACKUP_DIR}/${DATE}/nginx-proxy-manager.tar.gz -C /data/wiki nginx-proxy-manager
tar -czf ${BACKUP_DIR}/${DATE}/compose.tar.gz -C /data/wiki docker-compose.yml

find ${BACKUP_DIR} -maxdepth 1 -type d -mtime +14 -exec rm -rf {} \;

echo "Backup completed: ${BACKUP_DIR}/${DATE}"

授权执行：

chmod +x /data/wiki/backup/backup.sh

添加定时任务：

crontab -e

每天凌晨 2 点备份：

0 2 * * * /data/wiki/backup/backup.sh >> /data/wiki/backup/backup.log 2>&1

3. 备份异地存储

本机备份不能替代异地备份。服务器磁盘损坏、误删除、勒索病毒、机房故障都可能导致本机备份不可用。

建议至少选择一种异地备份方式：

• 备份到 NAS；
• 备份到对象存储，例如 S3、MinIO、阿里云 OSS、腾讯云 COS；
• 使用 rsync 同步到另一台服务器；
• 使用专业备份软件，例如 Restic、Duplicati、BorgBackup。

4. 定期恢复演练

没有验证过的备份不是真正的备份。建议每月至少做一次恢复演练，在测试服务器上完整恢复知识库，确认数据库、附件、权限、登录、证书配置是否正常。

十、升级策略与回滚方案

知识库系统上线后，升级不能简单执行：

docker compose pull
docker compose up -d

虽然这在测试环境中通常没问题，但生产环境必须谨慎。

1. 升级前准备

升级前建议完成以下事项：

• 阅读官方 Release Notes；
• 确认是否有数据库结构变更；
• 查看是否存在破坏性更新；
• 完整备份数据库和文件；
• 在测试环境先升级验证；
• 准备回滚镜像版本；
• 选择低峰时间升级。

2. 固定镜像版本

生产环境不建议长期使用 latest 标签。更推荐指定明确版本，例如：

image: ghcr.io/requarks/wiki:2.5

这样可以避免某次重启后意外拉取新版本导致不可控问题。

3. 回滚思路

如果升级失败，可以：

1. 停止当前容器；
2. 恢复旧版本镜像；
3. 如数据库已变更，需要恢复升级前数据库备份；
4. 验证页面、登录、文档访问和附件是否正常。

命令示例：

docker compose down
# 修改 docker-compose.yml 中镜像版本
docker compose up -d

如果需要恢复数据库：

cat wiki.sql | docker exec -i wikijs-postgres psql -U wikijs -d wiki

十一、监控与日志

知识库是企业内部高频使用系统，一旦无法访问，会影响团队协作。因此需要基础监控。

1. 容器状态检查

可以使用：

docker ps
docker stats

查看运行状态和资源占用。

2. 查看应用日志

docker logs -f wikijs-app
docker logs -f wikijs-postgres
docker logs -f nginx-proxy-manager

3. 接入监控系统

如果企业已有监控平台，可以接入：

• Prometheus + Grafana；
• Zabbix；
• Uptime Kuma；
• 夜莺监控；
• 阿里云云监控；
• 腾讯云可观测平台。

对于中小团队，推荐先部署 Uptime Kuma，对知识库域名做 HTTP 状态监控，并配置企业微信、飞书、钉钉或邮件告警。

监控项至少包括：

• 页面是否可访问；
• HTTPS 证书是否即将过期；
• 容器是否运行；
• 磁盘空间是否不足；
• CPU 和内存是否异常；
• 数据库连接是否异常；
• 备份任务是否成功。

十二、生产环境实测问题与处理经验

下面整理一些实际部署中经常遇到的问题。

1. 访问域名后页面资源加载异常

常见原因是反向代理未正确配置 WebSocket 或 HTTPS 强制跳转异常。建议检查：

• Nginx Proxy Manager 是否开启 Websockets Support；
• Wiki.js 站点 URL 是否配置为 HTTPS 域名；
• 浏览器控制台是否有 Mixed Content 报错；
• 反向代理是否传递了 X-Forwarded-Proto。

2. 上传图片失败

可能原因包括：

• 文件大小超过限制；
• 反向代理限制了上传大小；
• 容器目录权限异常；
• 磁盘空间不足。

如果使用 Nginx，可增加：

client_max_body_size 100M;

在 Nginx Proxy Manager 中可以通过 Advanced 配置添加相关参数。

3. 数据库连接失败

检查重点：

docker logs wikijs-app
docker logs wikijs-postgres

常见原因：

• 数据库密码不一致；
• PostgreSQL 容器未启动完成；
• Docker 网络配置错误；
• 数据库目录权限异常；
• 手动修改过数据库环境变量但旧数据目录仍保留旧配置。

需要注意的是，PostgreSQL 初始化后，环境变量中的密码变化不会自动修改已有数据库用户密码。

4. HTTPS 证书申请失败

常见原因：

• 域名未解析到服务器；
• 80 端口未开放；
• 防火墙或安全组拦截；
• 服务器位于内网，Let’s Encrypt 无法验证；
• 同一域名频繁申请触发限流。

如果知识库只在内网访问，可以使用企业内部 CA 证书，或通过 DNS Challenge 申请证书。

5. 磁盘空间快速增长

通常是附件、图片、备份文件增长导致。建议：

• 定期清理过期备份；
• 限制上传文件大小；
• 使用对象存储保存附件；
• 对大文件建立专门网盘或制品库，不建议全部塞入知识库；
• 配置磁盘空间告警。

十三、企业知识库内容运营建议

系统搭建完成只是第一步，真正难的是让团队持续使用。很多企业知识库失败的原因不是技术，而是没有内容治理机制。

1. 建立统一文档规范

建议制定基本规范：

• 标题清晰；
• 文档有创建人和更新时间；
• 重要文档有适用范围；
• 操作手册包含环境、步骤、风险、回滚；
• API 文档包含请求方式、参数、返回示例、错误码；
• 故障复盘包含时间线、影响范围、根因、改进措施。

2. 建立目录模板

例如故障复盘模板：

# 故障标题

## 一、故障概述

## 二、影响范围

## 三、时间线

## 四、根因分析

## 五、处理过程

## 六、改进措施

## 七、相关负责人

项目交接模板：

# 项目交接文档

## 项目背景

## 系统架构

## 部署环境

## 数据库说明

## 依赖服务

## 常见问题

## 运维联系人

## 风险点

3. 把知识库纳入流程

如果知识库只是“有空再写”，最终一定会荒废。建议把文档沉淀纳入实际流程：

• 项目上线必须补充部署文档；
• 接口变更必须更新 API 文档；
• 故障处理后必须提交复盘；
• 新人入职通过知识库完成学习；
• 版本发布必须记录变更说明；
• 离职交接必须完善相关文档。

4. 定期清理过期内容

知识库最怕内容过期。错误文档比没有文档更危险。建议每季度做一次文档巡检：

• 删除重复文档；
• 标记废弃内容；
• 更新过时截图；
• 修正失效链接；
• 合并相似页面；
• 检查权限是否合理。

十四、推荐的生产环境 Compose 示例

下面给出一个相对完整的 Compose 示例，适合作为生产环境基础模板使用。实际使用时请修改密码、域名、镜像版本和目录。

services:
  postgres:
    image: postgres:15
    container_name: wikijs-postgres
    restart: always
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: your_strong_database_password
      TZ: Asia/Shanghai
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    networks:
      - wiki-net

  wikijs:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs-app
    restart: always
    depends_on:
      - postgres
    environment:
      DB_TYPE: postgres
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: your_strong_database_password
      DB_NAME: wiki
      TZ: Asia/Shanghai
    networks:
      - wiki-net

  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    restart: always
    ports:
      - "80:80"
      - "81:81"
      - "443:443"
    volumes:
      - ./nginx-proxy-manager/data:/data
      - ./nginx-proxy-manager/letsencrypt:/etc/letsencrypt
    networks:
      - wiki-net

networks:
  wiki-net:
    driver: bridge

启动：

cd /data/wiki
docker compose up -d

查看：

docker ps

十五、上线检查清单

正式投入使用前，建议按以下清单检查：

• [ ] 管理员默认密码已修改；
• [ ] 数据库密码已使用强密码；
• [ ] 只开放必要端口；
• [ ] HTTPS 已启用；
• [ ] Wiki.js 站点 URL 配置正确；
• [ ] 上传图片和附件功能正常；
• [ ] 用户权限分组已规划；
• [ ] 数据库和配置文件已纳入备份；
• [ ] 备份脚本已定时执行；
• [ ] 已完成一次恢复演练；
• [ ] 已配置磁盘空间告警；
• [ ] 已配置站点可用性监控；
• [ ] 已建立文档规范和负责人机制；
• [ ] 已确认升级和回滚方案。

十六、总结

使用 Docker 搭建企业知识库并不复杂，真正的难点在于生产环境的稳定性、安全性和长期运营。本文以 Wiki.js、PostgreSQL 和 Nginx Proxy Manager 为例，完整介绍了从服务器规划、容器部署、反向代理、HTTPS、安全加固、权限设计、备份恢复、升级策略到内容运营的实践经验。

对于中小企业而言，Docker Compose 是一种非常务实的方案：部署简单、维护成本低、迁移方便，也便于后续扩展。如果团队规模继续扩大，后续可以再考虑接入对象存储、统一认证、全文搜索、集中日志、监控告警，甚至迁移到 Kubernetes。

最后需要强调的是：知识库的价值不在于系统有多复杂，而在于团队是否持续使用、持续维护、持续沉淀。 技术平台只是基础，文档规范、权限治理、备份机制和内容运营，才是企业知识库能够长期发挥价值的关键。