Debian 12 部署企业知识库：Wiki.js、PostgreSQL 与 Nginx 完整配置指南

发布人：慈云数据-客服中心发布时间：13小时前阅读量：4

Debian 企业知识库搭建｜附配置文件

在企业内部，知识库通常用于沉淀运维文档、项目规范、故障案例、研发流程、制度说明、接口文档以及新人培训资料。相比把文档分散在个人电脑、聊天记录或网盘中，统一的企业知识库可以显著提升信息检索效率，减少重复沟通成本，并降低人员流动带来的知识断层风险。

本文以 Debian 12 为基础系统，介绍一种较为通用、易维护的企业知识库搭建方案：使用 Wiki.js + PostgreSQL + Nginx。Wiki.js 支持 Markdown、权限管理、搜索、版本历史、用户认证、附件上传等功能，适合中小型团队或企业内部使用。本文同时附带完整配置文件，方便直接落地部署。

一、方案概述

本方案采用如下架构：

用户浏览器
    |
    | HTTPS
    |
Nginx 反向代理
    |
    | HTTP 3000
    |
Wiki.js 应用
    |
    | TCP 5432
    |
PostgreSQL 数据库

组件说明

组件	作用
Debian 12	服务器操作系统
Wiki.js	企业知识库系统
PostgreSQL	存储知识库数据
Nginx	反向代理、HTTPS 终止
Docker Compose	管理应用容器
Certbot	申请 Let’s Encrypt HTTPS 证书

场景	CPU	内存	磁盘
10~50 人团队	2 核	4 GB	50 GB SSD
50~200 人团队	4 核	8 GB	100 GB SSD
200 人以上	8 核+	16 GB+	独立数据库或对象存储

二、基础环境准备

1. 更新系统

sudo apt update
sudo apt upgrade -y

安装常用工具：

sudo apt install -y curl wget vim git gnupg2 ca-certificates lsb-release ufw

查看系统版本：

cat /etc/debian_version

建议使用 Debian 12 或更新版本。

三、安装 Docker 与 Docker Compose

Wiki.js 可以直接使用 Node.js 部署，但在企业环境中更推荐使用 Docker Compose，原因是：

部署过程标准化；
升级和回滚更方便；
配置集中，便于迁移；
对系统环境污染较小。

1. 安装 Docker

执行以下命令安装 Docker：

sudo apt install -y docker.io docker-compose-plugin

启动并设置开机自启：

sudo systemctl enable docker
sudo systemctl start docker

验证版本：

docker --version
docker compose version

2. 创建部署目录

建议将知识库相关文件统一放在 /opt/wiki：

sudo mkdir -p /opt/wiki
sudo mkdir -p /opt/wiki/postgres
sudo mkdir -p /opt/wiki/wiki-data
sudo mkdir -p /opt/wiki/backup
sudo chown -R $USER:$USER /opt/wiki
cd /opt/wiki

目录说明：

/opt/wiki
├── docker-compose.yml      # Docker Compose 配置
├── postgres/               # PostgreSQL 数据目录
├── wiki-data/              # Wiki.js 数据目录，可用于扩展
└── backup/                 # 备份目录

四、编写 Docker Compose 配置文件

在 /opt/wiki 目录下创建 docker-compose.yml：

vim /opt/wiki/docker-compose.yml

写入以下内容：

version: "3.8"

services:
  db:
    image: postgres:15-alpine
    container_name: wikijs-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: "请修改为强密码"
      TZ: Asia/Shanghai
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - wiki-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs -d wikijs"]
      interval: 10s
      timeout: 5s
      retries: 5

  wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: "请修改为强密码"
      DB_NAME: wikijs
      TZ: Asia/Shanghai
    ports:
      - "127.0.0.1:3000:3000"
    networks:
      - wiki-net

networks:
  wiki-net:
    driver: bridge

注意：POSTGRES_PASSWORD 和 DB_PASS 必须保持一致，并且务必修改为复杂密码，例如包含大小写字母、数字和特殊字符。

启动服务

cd /opt/wiki
docker compose up -d

查看容器状态：

docker ps

查看日志：

docker logs -f wikijs

如果看到 Wiki.js 正常启动，即可继续配置 Nginx。

五、安装并配置 Nginx 反向代理

1. 安装 Nginx

sudo apt install -y nginx

启动并设置开机自启：

sudo systemctl enable nginx
sudo systemctl start nginx

2. 准备域名

假设企业知识库域名为：

wiki.example.com

请在 DNS 服务商处添加 A 记录：

wiki.example.com -> 服务器公网 IP

如果是纯内网环境，可以在内网 DNS 中添加解析，或在客户端 hosts 文件中配置解析。

六、Nginx HTTP 配置文件

创建 Nginx 站点配置：

sudo vim /etc/nginx/sites-available/wiki.conf

写入以下内容：

server {
    listen 80;
    server_name wiki.example.com;

    client_max_body_size 200m;

    access_log /var/log/nginx/wiki_access.log;
    error_log  /var/log/nginx/wiki_error.log;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

启用站点：

sudo ln -s /etc/nginx/sites-available/wiki.conf /etc/nginx/sites-enabled/wiki.conf

检查配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

此时可以通过浏览器访问：

http://wiki.example.com

首次访问会进入 Wiki.js 初始化页面，根据提示创建管理员账号、设置站点名称和访问地址即可。

七、配置 HTTPS 证书

企业知识库涉及内部资料，建议强制启用 HTTPS。

1. 安装 Certbot

sudo apt install -y certbot python3-certbot-nginx

2. 申请证书

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

根据提示选择是否强制跳转 HTTPS，建议选择自动重定向。

3. HTTPS 版 Nginx 配置参考

Certbot 自动修改后，配置大致如下：

server {
    listen 80;
    server_name wiki.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wiki.example.com;

    client_max_body_size 200m;

    access_log /var/log/nginx/wiki_access.log;
    error_log  /var/log/nginx/wiki_error.log;

    ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

测试证书自动续期：

sudo certbot renew --dry-run

八、防火墙配置

如果使用 Debian 自带的 UFW，可以只开放 SSH、HTTP 和 HTTPS：

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

由于 Docker Compose 中 Wiki.js 只绑定到 127.0.0.1:3000，外部无法直接访问 3000 端口，只能通过 Nginx 访问，这样安全性更好。

九、Wiki.js 初始化配置建议

首次进入 Wiki.js 后，需要完成初始化。以下配置建议适合企业内部使用。

1. 站点名称

例如：

企业知识库

或：

XX 公司研发知识中心

2. 默认语言

建议选择：

Chinese Simplified

即简体中文。

3. 访问地址

如果启用了 HTTPS，应填写：

https://wiki.example.com

4. 权限策略

建议不要开放匿名编辑。常见权限策略如下：

角色	权限
管理员	全局配置、用户管理、权限管理
编辑者	创建、编辑、发布文档
普通成员	查看文档、评论
访客	禁止访问或仅查看公开页面

对于企业内部知识库，推荐默认关闭匿名访问，所有用户必须登录后才能查看内容。

十、企业知识库栏目规划

知识库不是搭建完成就结束了，真正重要的是内容组织。建议按照企业业务和部门进行规划。

文档命名规范

建议使用统一命名方式，例如：

[系统名称] 操作说明
[项目名称] 部署文档
[故障编号] 故障复盘报告
[接口名称] API 调用说明

示例：

订单系统生产环境部署文档
Redis 主从切换操作手册
2024-06-15 支付服务超时故障复盘
用户登录接口 API 文档

十一、Markdown 文档模板

为了保证知识库内容质量，建议提供统一模板。以下是一个运维文档模板：

# 文档标题

## 一、文档信息

| 项目 | 内容 |
|---|---|
| 系统名称 |  |
| 负责人 |  |
| 创建时间 |  |
| 更新时间 |  |
| 适用环境 | 测试 / 预生产 / 生产 |

## 二、背景说明

说明本文档适用场景、解决的问题以及注意事项。

## 三、操作步骤

### 1. 前置检查

```bash
命令示例

2. 执行操作

命令示例

3. 验证结果

命令示例

四、回滚方案

如果操作失败，按照以下步骤回滚：

步骤一；
步骤二；
步骤三。

五、风险说明

风险点	影响	应对措施

六、相关链接

链接一
链接二

故障复盘模板：

# 故障复盘：YYYY-MM-DD 故障标题

## 一、故障概述

| 项目 | 内容 |
|---|---|
| 故障时间 |  |
| 影响范围 |  |
| 故障等级 | P1 / P2 / P3 |
| 负责人 |  |
| 当前状态 | 已恢复 / 处理中 |

## 二、时间线

| 时间 | 事件 |
|---|---|
| 10:00 | 监控告警触发 |
| 10:05 | 值班人员确认问题 |
| 10:20 | 定位原因 |
| 10:35 | 恢复服务 |

## 三、根因分析

描述导致故障的直接原因和深层原因。

## 四、处理过程

记录排查和恢复过程。

## 五、改进措施

| 改进项 | 负责人 | 截止时间 | 状态 |
|---|---|---|---|
|  |  |  |  |

十二、数据库备份配置

知识库最重要的是数据。无论系统多稳定，都必须配置备份。

1. 创建备份脚本

创建脚本目录：

sudo mkdir -p /opt/wiki/scripts
sudo vim /opt/wiki/scripts/backup-wiki.sh

写入以下内容：

#!/bin/bash

set -e

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

mkdir -p ${BACKUP_DIR}

echo "开始备份 Wiki.js 数据库..."

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

gzip ${BACKUP_DIR}/wikijs_${DATE}.sql

echo "清理 30 天前的备份文件..."
find ${BACKUP_DIR} -name "wikijs_*.sql.gz" -type f -mtime +30 -delete

echo "备份完成：${BACKUP_DIR}/wikijs_${DATE}.sql.gz"

赋予执行权限：

sudo chmod +x /opt/wiki/scripts/backup-wiki.sh

手动执行测试：

sudo /opt/wiki/scripts/backup-wiki.sh

2. 配置定时任务

每天凌晨 2 点自动备份：

sudo crontab -e

加入：

0 2 * * * /opt/wiki/scripts/backup-wiki.sh >> /var/log/wiki-backup.log 2>&1

查看日志：

tail -f /var/log/wiki-backup.log

十三、数据库恢复方法

如果需要从备份恢复数据库，可以按以下步骤操作。

1. 停止 Wiki.js 应用

cd /opt/wiki
docker compose stop wiki

2. 解压备份文件

gunzip -c /opt/wiki/backup/wikijs_2024-06-01_02-00-00.sql.gz > /tmp/wikijs_restore.sql

3. 清空并恢复数据库

docker exec -i wikijs-postgres psql -U wikijs -d wikijs -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
docker exec -i wikijs-postgres psql -U wikijs -d wikijs < /tmp/wikijs_restore.sql

4. 启动 Wiki.js

docker compose start wiki

确认访问正常后，删除临时文件：

rm -f /tmp/wikijs_restore.sql

十四、升级 Wiki.js

使用 Docker Compose 部署后，升级非常简单。

cd /opt/wiki
docker compose pull
docker compose up -d

升级前建议先备份数据库：

sudo /opt/wiki/scripts/backup-wiki.sh

升级后查看日志：

docker logs -f wikijs

如果升级后出现异常，可回滚到指定镜像版本。例如将：

image: ghcr.io/requarks/wiki:2

改为某个具体版本：

image: ghcr.io/requarks/wiki:2.5

然后重新启动：

docker compose up -d

生产环境中建议不要盲目使用 latest 标签，最好固定版本，经过测试后再升级。

十五、安全加固建议

1. 使用强密码

数据库密码、管理员密码必须使用强密码，并定期更换。

2. 限制 SSH 登录

建议禁止 root 直接登录：

sudo vim /etc/ssh/sshd_config

修改：

PermitRootLogin no
PasswordAuthentication no

然后重启 SSH：

sudo systemctl restart ssh

使用密钥登录前，请确认密钥已经配置成功，避免把自己锁在服务器外。

3. 开启 HTTPS

不要在生产环境中使用明文 HTTP，尤其是知识库中包含账号、系统架构、部署流程等敏感内容时。

4. 定期备份并异地保存

仅在本机保存备份是不够的。如果服务器磁盘损坏，本机备份也会一起丢失。建议将备份同步到：

内网 NAS；
对象存储；
备份服务器；
企业云盘；
异地数据中心。

可以使用 rsync 或 rclone 实现远程同步。

5. 最小权限原则

不要给所有人管理员权限。管理员账号越多，误操作和安全风险越高。

十六、常见问题排查

1. 页面无法访问

检查容器是否运行：

docker ps

检查 Wiki.js 日志：

docker logs wikijs

检查 Nginx：

sudo nginx -t
sudo systemctl status nginx

检查端口监听：

ss -lntp

2. 数据库连接失败

确认 docker-compose.yml 中以下配置一致：

POSTGRES_DB: wikijs
POSTGRES_USER: wikijs
POSTGRES_PASSWORD: "请修改为强密码"

DB_USER: wikijs
DB_PASS: "请修改为强密码"
DB_NAME: wikijs

查看数据库容器日志：

docker logs wikijs-postgres

3. 上传附件失败

检查 Nginx 上传大小限制：

client_max_body_size 200m;

如果附件较大，可以调整为：

client_max_body_size 500m;

修改后重载 Nginx：

sudo nginx -t
sudo systemctl reload nginx

4. HTTPS 证书申请失败

检查域名是否正确解析：

ping wiki.example.com

检查 80 端口是否开放：

sudo ufw status

确认 Nginx 配置无误：

sudo nginx -t

十七、生产环境优化建议

1. 数据库独立部署

当用户数量较多或知识库访问频繁时，可以将 PostgreSQL 独立部署到专用数据库服务器，或使用企业已有的数据库集群。

2. 配置监控告警

建议监控以下指标：

CPU 使用率；
内存使用率；
磁盘容量；
Docker 容器状态；
PostgreSQL 连接数；
Nginx 5xx 错误数量；
HTTPS 证书到期时间。

可以使用 Prometheus、Grafana、Zabbix 或企业已有监控系统。

3. 制定文档治理规则

知识库上线后，如果没有治理规则，很容易变成“文档垃圾场”。建议制定以下制度：

每篇文档必须有负责人；
重要文档至少每季度复审一次；
过期文档必须归档或删除；
生产操作文档必须经过评审；
故障复盘必须在故障恢复后一周内完成；
文档标题、目录、标签必须规范。

十八、完整配置文件汇总

1. `/opt/wiki/docker-compose.yml`

version: "3.8"

services:
  db:
    image: postgres:15-alpine
    container_name: wikijs-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: "请修改为强密码"
      TZ: Asia/Shanghai
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - wiki-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs -d wikijs"]
      interval: 10s
      timeout: 5s
      retries: 5

  wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: "请修改为强密码"
      DB_NAME: wikijs
      TZ: Asia/Shanghai
    ports:
      - "127.0.0.1:3000:3000"
    networks:
      - wiki-net

networks:
  wiki-net:
    driver: bridge

2. `/etc/nginx/sites-available/wiki.conf`

server {
    listen 80;
    server_name wiki.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wiki.example.com;

    client_max_body_size 200m;

    access_log /var/log/nginx/wiki_access.log;
    error_log  /var/log/nginx/wiki_error.log;

    ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

3. `/opt/wiki/scripts/backup-wiki.sh`

#!/bin/bash

set -e

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

mkdir -p ${BACKUP_DIR}

echo "开始备份 Wiki.js 数据库..."

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

gzip ${BACKUP_DIR}/wikijs_${DATE}.sql

echo "清理 30 天前的备份文件..."
find ${BACKUP_DIR} -name "wikijs_*.sql.gz" -type f -mtime +30 -delete

echo "备份完成：${BACKUP_DIR}/wikijs_${DATE}.sql.gz"

十九、总结

本文基于 Debian 12 搭建了一套企业知识库系统，核心组件包括 Wiki.js、PostgreSQL、Nginx 和 Docker Compose。该方案部署简单、维护成本低、扩展性较好，适合多数企业内部知识沉淀场景。

需要特别强调的是，知识库建设并不是单纯安装一个系统，而是一项长期的组织管理工作。系统解决的是“文档放在哪里”的问题，而制度和流程解决的是“谁来写、怎么写、多久更新、如何保证质量”的问题。只有将技术平台、权限体系、备份策略和文档治理结合起来，企业知识库才能真正发挥价值。

文章标签： Debian12 Wiki.js PostgreSQL Nginx

上一篇：站长实战：用 Debian 搭建稳定安全的企业知识库系统

下一篇：Debian 12 部署企业知识库：BookStack 从安装到备份配置实战

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们

Debian 12 部署企业知识库：Wiki.js、PostgreSQL 与 Nginx 完整配置指南

Debian 企业知识库搭建｜附配置文件

一、方案概述

组件说明

推荐服务器配置

二、基础环境准备

1. 更新系统

三、安装 Docker 与 Docker Compose

1. 安装 Docker

2. 创建部署目录

四、编写 Docker Compose 配置文件

启动服务

五、安装并配置 Nginx 反向代理

1. 安装 Nginx

2. 准备域名

六、Nginx HTTP 配置文件

七、配置 HTTPS 证书

1. 安装 Certbot

2. 申请证书

3. HTTPS 版 Nginx 配置参考

八、防火墙配置

九、Wiki.js 初始化配置建议

1. 站点名称

2. 默认语言

3. 访问地址

4. 权限策略

十、企业知识库栏目规划

推荐目录结构

文档命名规范

十一、Markdown 文档模板

2. 执行操作

3. 验证结果

四、回滚方案

五、风险说明

六、相关链接

十二、数据库备份配置

1. 创建备份脚本

2. 配置定时任务

十三、数据库恢复方法

1. 停止 Wiki.js 应用

2. 解压备份文件

3. 清空并恢复数据库

4. 启动 Wiki.js

十四、升级 Wiki.js

十五、安全加固建议

1. 使用强密码

2. 限制 SSH 登录

3. 开启 HTTPS

4. 定期备份并异地保存

5. 最小权限原则

十六、常见问题排查

1. 页面无法访问

2. 数据库连接失败

3. 上传附件失败

4. HTTPS 证书申请失败

十七、生产环境优化建议

1. 数据库独立部署

2. 配置监控告警

3. 制定文档治理规则

十八、完整配置文件汇总

1. /opt/wiki/docker-compose.yml

2. /etc/nginx/sites-available/wiki.conf

3. /opt/wiki/scripts/backup-wiki.sh

十九、总结

1. `/opt/wiki/docker-compose.yml`

2. `/etc/nginx/sites-available/wiki.conf`

3. `/opt/wiki/scripts/backup-wiki.sh`