Linux怎样安装Wiki.js知识库

Docker Compose一键部署Wiki.js最省心，无需手动配置Node.js、数据库驱动和系统服务；官方镜像ghcr.io/requarks/wiki:2预编译所有依赖，配合PostgreSQL容器可全自动运行；关键在于正确配置docker-compose.yml中的DB_PASS（避免特殊字符）、volume名称一致性及防火墙/安全组端口放行。

用 Docker Compose 一键拉起最省心

绝大多数 Linux 用户（Ubuntu/CentOS/Rocky 等）直接走 Docker 方案，不用管 Node.js 版本、数据库驱动兼容性、端口冲突这些琐事。官方镜像 ghcr.io/requarks/wiki:2 已预编译所有依赖，连 PostgreSQL 都能一起跑。

关键不是“能不能装”，而是“别手动装 Node + npm + config.yml + systemd service”。Docker Compose 把整套环境锁死在声明式文件里，升级只需改 image 标签再 docker-compose pull && docker-compose up -d。

• 确保已安装 docker 和 docker-compose-plugin（新版 Docker 自带，不用单独装 docker-compose 二进制）
• docker-compose.yml 中的 DB_PASS 必须是纯文本密码，不能含特殊字符如 $、{、}，否则 PostgreSQL 客户端解析失败（常见报错：connection refused 或 invalid password）
• PostgreSQL 容器首次启动会初始化数据库，但若反复删容器重跑，volumes 没配对（比如 db-data 名字拼错），数据就丢了——db-data 和 wiki-data 两个 volume 名必须和 yml 里完全一致

非 Docker 方式：Node.js 版本踩坑最多

Wiki.js 明确要求 Node.js ≥18.0.0，且 不支持奇数版本（如 v19.x、v21.x）。很多用户用 apt install nodejs 装到 v12 或 v16，结果 node server 直接报 ERR_UNSUPPORTED_ESM_URL_SCHEME 或 Cannot find module 'node:fs'。

• Ubuntu/Debian 推荐用 Nodesource 源装 v20：curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs
• CentOS/RHEL 用 EPEL + Nodesource：sudo yum install epel-release && curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - && sudo yum install -y nodejs
• config.yml 里 db.type 填 postgres 就必须装 pg 包，填 mariadb 就得装 mariadb 客户端库，否则启动时提示 Cannot find module 'mariadb' —— 这个错误不会在 npm install 阶段暴露，而是在 node server 时才炸

数据库权限配置最容易漏掉的点

PostgreSQL 或 MariaDB 装完只是开始，Wiki.js 连不上往往卡在权限上。不是密码错，而是用户没授权、监听没开、认证方式不对。

• PostgreSQL：检查 /var/lib/postgresql/data/pg_hba.conf 是否有这行：host all all 0.0.0.0/0 md5（允许任意 IP 用密码连接），然后 sudo systemctl restart postgresql
• MariaDB：执行 GRANT ALL ON wikijs.* TO 'wikijs'@'%' IDENTIFIED BY 'yourpass'; FLUSH PRIVILEGES;，@'localhost' 不够用，因为 Wiki.js 容器内访问的是宿主机 IP，不是 127.0.0.1
• SQLite 最省事但别用于多用户场景：db.type: sqlite + db.storage: /var/wiki/data.db 即可，但并发编辑会锁表，页面保存失败率高

启动后打不开 http://IP:3000？先查这三件事

容器跑起来了、日志没报错，但浏览器白屏或连接被拒绝，问题通常不在 Wiki.js 本身。

• 防火墙：Ubuntu ufw 默认关 3000 端口，运行 sudo ufw allow 3000；CentOS firewalld 执行 sudo firewall-cmd --add-port=3000/tcp --permanent && sudo firewall-cmd --reload
• Docker 网络：确认 docker-compose.yml 里 wiki 服务的 ports 是 - "3000:3000"，不是 - "3000:80" 或漏写冒号
• 云服务器安全组：阿里云/腾讯云后台必须手动放行 3000 端口，光开本地防火墙没用

真正麻烦的从来不是安装步骤，而是数据库网络策略、Docker volume 持久化路径、Node.js ABI 兼容性这三块——它们不出错时无声无息，一出就是 2 小时排查起步。