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；CentOSfirewalld执行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 小时排查起步。
