极空间NAS部署Wiki.js知识库：Docker与PostgreSQL完整实战指南

我前前后后折腾了好几套知识库方案从语雀到Notion再从Confluence到MkDocs最后在极空间NAS上用Docker把Wiki.js跑了起来配合PostgreSQL做存储算是彻底稳定下来了。这个组合做完之后我身边好几个玩NAS的朋友都跑来问怎么搭的说实话网上现成的教程虽然有但大多只讲了“怎么敲命令”没讲清楚每一步为什么要这么做更没提示那些真正会坑到你的细节。这篇文章我把完整的部署过程、参数选择和踩坑记录都整理出来照着走就行。不管你是刚入手极空间、对Docker一脸懵的小白还是已经折腾过一段时间、想找一个靠谱内网知识库方案的NAS玩家这篇文章都适用。我会尽量把每个关键决策背后的逻辑讲明白这样你后续遇到问题也能自己判断不用到处翻资料。1. 方案选型拆解这个组合为什么值得折腾1.1 知识库软件对比Wiki.js赢在哪先说说我为什么最终选了Wiki.js。网上讨论比较多的是Confluence和Notion这俩确实是好东西但在NAS这种场景下都有自己的硬伤。Confluence对内存的要求极其苛刻官方推荐配置就是4GB起步极空间NAS虽然有多个型号但你要是还在跑其他容器内存很容易吃紧。更重要的是Confluence是商业授权自己玩还行严格来说商用是存在授权风险的。Notion则是纯云端产品数据全部在别人服务器上对于想把知识资产完全握在自己手里的人来说这一步过不去。Wiki.js这个项目在这几个维度上正好都踩在了点上。它是完全开源的GPLv3协议想怎么用都行支持Markdown语法技术文档写起来很顺手它还内置了Git同步能力你写的每一篇文档都能推送到远程仓库等于多了一层版本备份。最打动我的一点是它的模块化设计认证方式、编辑器、存储引擎都可以通过装插件来扩展后面想接LDAP或者钉钉登录都不是难事。从UI层面来说Wiki.js的界面风格更偏现代化团队协作工具不是那种老气横秋的百科系统家庭和团队场景都撑得起来。1.2 数据库选型为什么不偷懒用SQLiteWiki.js官方有两种数据库选择一个是SQLite一个是PostgreSQL。很多人图省事部署的时候直接选了SQLite我当时也纠结过但研究完决定必须上PostgreSQL理由很实在。SQLite说白了就是单文件数据库优点只有一个简单。但缺点非常致命它是写锁库级别的并发控制Wiki.js在过程编辑权限管理、同时多个页面写入这种场景下SQLite会频繁出现“database is locked”这类报错。还有一个问题是备份和恢复的灵活性太低数据库文件一旦损坏基本没有抢救空间。PostgreSQL虽然部署成本高一些但它提供的是真正的客户端/服务器架构并发能力远超SQLite而且它支持在线备份、时间点恢复这类企业级功能后续做备份脚本会舒服很多。另外一个很多人没考虑到的点是PostgreSQL不只是给Wiki.js用的。你后面如果要在NAS上部署其他业务系统比如Gitea、Nextcloud的一些增强组件甚至是一个专门的报表服务PostgreSQL都可以顺手承担下来一次部署多处受益。这笔投入不亏。1.3 为什么要在Docker里跑而不是直接装极空间ZOS是基于Linux内核的理论上确实可以像在普通服务器上一样直接在系统里装PostgreSQL和Node.js然后用进程方式跑。但我强烈不建议这么干核心原因是环境隔离和运维一致性。NAS上的系统盘空间有限本身ZOS就会自动升级系统你如果在系统层面装了不少依赖库系统升级时极有可能出现依赖冲突轻则服务起不来重则影响NAS本身的稳定性。Docker容器把所有依赖都打包在镜像里对宿主机文件系统只做有限的挂载访问隔离性很好。而且极空间自带Docker管理界面容器状态、日志、重启策略都可以可视化查看这比纯命令行管理要友好太多。后续如果想升级Wiki.js版本只需要拉新镜像重新起容器旧版本还留在原地回滚也非常方便。2. 部署前准备极空间Docker环境与目录规划2.1 极空间Docker功能入口与设置极空间ZOS系统在应用中心里自带了Docker服务不管你是Z2S还是Z4系列入口都在“应用中心”里的“Docker”图标。第一次打开会提示初始化Docker环境这个操作只需要等一分钟左右它会把Docker守护进程拉起来。初始化完成之后我建议你先不要急着去拉镜像先去检查一下“镜像”分类下的“镜像加速器”配置。这一步很关键因为极空间默认的镜像源在国内访问速度非常不稳定如果不配置加速器拉取postgres和wikijs这两个镜像的时候可能会等到怀疑人生。配置方式和国内主流云厂商给的要完全一样把你已有的加速地址填进去保存后重新拉镜像才生效。实测下来配置加速器和没配置至少有三到五倍的速度差距。2.2 建议目录结构与路径规划Docker容器跑起来之后所有数据都必须落到NAS的存储空间里否则容器一删数据全没了。极空间的文件系统挂载路径和通用Linux发行版不太一样我强烈建议在开始部署之前先把目录结构和路径理清楚这会直接影响后续的备份恢复效率。我自己是这样规划的供你参考。在极空间文件管理里创建一个名为docker的共享文件夹然后在其下分别建立postgres和wiki两个子目录。postgres目录用于持久化PostgreSQL的数据文件wiki目录用于存放Wiki.js的配置文件和后续的备份产物。/vol1/docker/postgres - PostgreSQL数据文件 /vol1/docker/wiki - Wiki.js配置和备份文件强调一个极其容易踩坑的点极空间在Docker容器里映射宿主目录时默认显示的路径可能包含/tmp前缀比如/tmp/vol1/docker/postgres这个并不是你真实的系统路径。真实路径一般是从/vol1或者你设置的存储池根路径开始的。你在填映射路径的时候务必要手动选择你创建的文件夹并且确认容器内看到的路径没有被映射到一个重启后会丢失的临时目录。我就见过有用户映射到了/tmp路径结果NAS一重启数据库文件只剩一个空壳。2.3 开启SSH终端以提升部署效率极空间的Docker图形界面虽然能创建容器但可用选项非常有限尤其是设置网络模式、添加环境变量、调整资源限制这些内容图形界面操作起来很费劲。我的建议是开启极空间的SSH服务然后用终端工具连上去执行命令。SSH入口在极空间系统设置里的“远程访问”或者“终端”选项开启后会有一个SSH地址和端口。如果你之前没有用过SSH我简单说一句流程在电脑上下载一个叫“Termius”或者直接用Windows自带的Terminal执行ssh 用户名IP地址 -p 端口输入密码就进去了。极空间默认端口一般不是22你自己在设置界面里看一眼端口号就行。第一次连上SSH后先用sudo -i切换到root身份后面执行docker命令会更顺手否则每条命令前面都要加sudo。开启SSH不仅是部署这一件事需要后续排查容器日志、查看PostgreSQL执行计划、手动执行数据库备份全部都要用到命令行。强烈建议你现在就把它打开。3. 部署PostgreSQL容器核心参数与数据持久化3.1 镜像版本选型与拉取PostgreSQL的镜像版本比较多从9到16都有。我的建议是选择postgres:16-alpine原因有两个第一16是目前稳定版的较新版本Wiki.js官方对PostgreSQL 12以上的支持都很成熟选16不会有兼容性问题第二alpine版本镜像体积小运行内存占用也低于标准版这在NAS场景下是实打实的好处。在SSH终端执行拉取命令docker pull postgres:16-alpine拉取完成后可以用docker images看一眼镜像是否就位确保IMAGE ID和TAG都没问题。到这里镜像就准备好了。3.2 创建独立Docker网络容器之间通信有两种方案一种是使用宿主机IP加映射端口另一种是创建一个Docker内部网络让容器之间直接用容器名访问。我推荐第二种可靠性更高不依赖网络环境变化。使用以下命令创建一个自定义网络名字就叫wiki-networkdocker network create wiki-network后面PostgreSQL和Wiki.js两个容器都连接到这个网络里。这样Wiki.js连接数据库时数据库地址直接写postgres这个容器名即可Docker内部的DNS服务会自动解析到对应IP速度极快且不受宿主机网络变化影响。3.3 启动PostgreSQL容器与参数解释启动PostgreSQL容器时有几个环境变量必须设对分别是POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB。这三个变量定义了数据库超级用户、密码以及初始数据库名称。我建议不要把超级用户直接给Wiki.js用而是创建好数据库之后再单独建一个专用账号。但如果你只是家里自用追求简单直接用超级用户建库也不是不行。下面的命令展示了标准的启动方式docker run -d \ --name postgres \ --restart always \ --network wiki-network \ -e POSTGRES_USERwikijs \ -e POSTGRES_PASSWORDYourStrongPassword \ -e POSTGRES_DBwiki \ -v /vol1/docker/postgres:/var/lib/postgresql/data \ -p 127.0.0.1:5432:5432 \ postgres:16-alpine逐个参数说明一下。--restart always表示容器如果意外退出Docker守护进程会自动把它重新拉起来这是NAS服务必须的条件否则NAS重启一下数据库没起来Wiki.js就会出现一堆连接错误。-v参数把宿主目录映射到容器内的数据目录这是PostgreSQL数据持久化的关键没有这一步数据库容器一删就是灭顶之灾。端口映射这里有一个细节。我写的是127.0.0.1:5432:5432这意味着只有宿主机本机可以访问这个端口。为什么这么干因为极空间NAS如果直接把5432端口暴露在局域网里任何内网设备都能直接尝试连接你的数据库增加了被爆破的风险。我们只需要Wiki.js容器通过网络访问数据库而容器之间走的是Docker内部网络完全不需要走宿主机端口。所以映射成回环地址就够了。3.4 验证PostgreSQL是否就绪启动之后先看一下容器状态docker ps如果看到postgres容器状态是Up说明已经起来了。但这还不能确保数据库能提供服务更稳妥的方式是直接执行容器内的命令验证docker exec -it postgres psql -U wikijs -d wiki -c SELECT version();如果能看到PostgreSQL的版本号输出说明数据库已经可以正常接受连接了。看到postgres:16这样的输出这一步就顺利通过了。4. 部署Wiki.js容器初始化流程与关键配置4.1 拉取镜像与启动命令Wiki.js官方镜像名是requarks/wiki建议拉取最新的2.x版本如下docker pull requarks/wiki:2然后启动容器docker run -d \ --name wikijs \ --restart always \ --network wiki-network \ -e DB_TYPEpostgres \ -e DB_HOSTpostgres \ -e DB_PORT5432 \ -e DB_USERwikijs \ -e DB_PASSYourStrongPassword \ -e DB_NAMEwiki \ -v /vol1/docker/wiki:/wiki/data \ -p 8080:3000 \ requarks/wiki:24.2 环境变量背后的逻辑Wiki.js部署最核心的环境变量就是几个以DB_开头的配置项。数据库类型值必须写成postgres不要写成postgresql或者pg写错的话容器启动时会提示数据库初始化失败。数据库地址写的是postgres也就是我们在同一个Docker网络里给数据库容器取的名字。这里必须要强调如果这两个容器不在同一个自定义网络里光写postgres是解析不了的必须写宿主机的局域网IP。数据库密码这里有一个容易忽略的坑如果你的密码里包含#、$、这类特殊字符在docker run命令里不做转义的话Shell可能会把它们当成特殊符号处理导致最终容器里的密码和你想的不一样。最简单稳妥的做法是密码只用大小写字母加数字组合虽然看起来不够“强”但在内网环境下这种复杂度已经足够。一定要用特殊字符的话请将整个变量用单引号括起来例如-e DB_PASSpssw0rd注意单双引号嵌套的顺序。4.3 首次启动与引导向导容器启动之后打开浏览器访问http://你的极空间IP:8080理论上会看到Wiki.js的初始化页面。第一次运行时Wiki.js会自动去连PostgreSQL并执行一系列建表操作。这一步可能会持续一两分钟如果你的极空间CPU是低功耗型号可能需要更长时间这段时间内页面可能会出现502或者空白都是正常的千万别以为装失败了等就完事了。初始化页面会让你创建管理员账号填邮箱地址和管理员密码。密码不要设太简单这毕竟是你整个知识库的管理员入口。创建完毕后系统会让你确认数据库连接信息这时候如果一切正常就会直接进入Wiki.js的主界面。4.4 配置极空间端口映射与防火墙检查很多极空间用户习惯了应用中心的自动端口分配以为服务起在8080端口就能直接外网访问。其实这里涉及到极空间的端口转发设置。如果你打算在外网也能访问这个Wiki就要在极空间的路由器管理界面或极空间自身的端口转发功能里把外部端口映射到这台极空间NAS的8080端口。但是我强烈建议在做端口映射时不要直接把8080暴露到公网。因为Wiki.js的默认配置没有足够强的防暴力破解能力如果你设置了弱密码被扫到的风险很高。更稳妥的做法是先用极空间的反向代理功能配一个SSL证书和域名用443端口对外提供HTTPS服务内部再转发到8080。这一步可能稍微复杂但这才是长期使用最健康的访问方式。5. 初始化后的系统设置与自动化备份实践5.1 数据备份的整体思路服务一旦跑起来最重要的就是备份策略。Wiki.js的数据本质上有两块一块是PostgreSQL数据库里的页面内容、用户账号、权限设置另一块是容器里挂在/wiki/data下的配置文件和上传附件。这两块必须同时备份缺一个都会导致恢复不完整。数据库备份用PostgreSQL自带的pg_dump工具。一个简单可靠的备份方式是在宿主机上执行docker exec -t postgres pg_dump -U wikijs -d wiki -F c -f /tmp/wiki_backup.dump docker cp postgres:/tmp/wiki_backup.dump /vol1/docker/wiki/wiki_backup_$(date %Y%m%d).dump这条命令的作用是先在容器内生成压缩格式的数据库备份然后复制到NAS的备份目录。-F c指定自定义格式这个格式独有的优势是恢复时可以灵活选择恢复整个数据库还是单张表。配置文件备份就更简单了直接把整个挂载目录复制走就行cp -r /vol1/docker/wiki /vol1/docker/wiki_backup_$(date %Y%m%d)5.2 定时任务的实现方式光有备份命令还不够还需要自动定时执行否则你忙起来肯定忘记。极空间支持配置计划任务也可以直接在宿主机上写crontab。在SSH终端里执行crontab -e添加一条每天凌晨3点执行的备份任务0 3 * * * docker exec -t postgres pg_dump -U wikijs -d wiki -F c -f /tmp/wiki_backup.dump docker cp postgres:/tmp/wiki_backup.dump /vol1/docker/wiki/wiki_backup_$(date \%Y\%m\%d).dump find /vol1/docker/wiki -name *.dump -mtime 7 -delete最后一段find命令的作用是自动删除7天前的备份文件避免备份文件无限积压把NAS的存储空间撑爆。这个保留天数你可以根据自己的使用频率来定。5.3 备份的恢复演练备份做完了一定要做一次恢复演练否则真到了要恢复的时候才发现备份文件有问题那才是真正的灾难。恢复命令如下docker exec -i postgres psql -U wikijs -d wiki -c DROP SCHEMA public CASCADE; CREATE SCHEMA public; docker exec -i postgres pg_restore -U wikijs -d wiki --clean --if-exists /tmp/wiki_backup.dump第一步先清空现有的公共模式然后再把备份文件导进去。这一步千万不能在业务高峰期执行它会有一段短暂的服务不可用时间你自己手动做恢复演练的时候要注意安排好窗口期。演练完之后刷新Wiki页面确认内容都还在就可以放心了。6. 常见问题与避坑经验速查6.1 高频故障与解决方案下面这份表格是我和一些NAS用户在实际部署和运维过程中遇到频率最高的问题一并整理出来供你对照排查。现象根本原因解决方式Wiki.js初始化页面一直转圈数据库连接失败多半是DB_HOST写错确认两个容器在同一网络执行docker network inspect wiki-network查看连接状态容器启动后马上退出环境变量DB_TYPE写错或密码带特殊字符查看日志docker logs wikijs按报错修正环境变量重新创建重启NAS后数据库数据丢失挂载路径映射到了/tmp开头的临时目录重新检查映射路径改用/vol1下的目录外网访问速度极慢外部端口和内部端口映射不稳定配置极空间反向代理使用HTTPS 443端口忘记管理员密码属于常见操作事故用数据库执行UPDATE users SET password...重置或者通过SSH进入容器运行重置命令6.2 PostgreSQL容器日志膨胀问题运行一段时间后你可能会发现极空间的存储空间在悄悄减少排查之后会发现postgres容器所在目录体积大得离谱。这是PostgreSQL一个比较正常的行为它的事务日志和统计信息会持续写入。但还有一种特殊情况会让日志疯长就是某个客户端反复连接失败这时PostgreSQL会把每次失败连接都记录下来。遇到日志疯长的情况先查看容器日志docker logs --tail 200 postgres如果发现报错信息里有大量连接失败记录通常就是Wiki.js连续重连导致的此时需要检查Wiki.js容器是否健康docker logs --tail 100 wikijs排查完问题之后可以对PostgreSQL做一次清理操作。进入容器执行下面的SQL语句即可自动清理旧日志和过期的临时文件VACUUM FULL;6.3 关于容器版本升级的实践经验Wiki.js的版本更新比较频繁修复了不少安全漏洞和功能bug。但升级之前一定要先备份这是我的绝对底线。升级操作本身不难拉新镜像、停旧容器、用相同参数重新创建并挂载原有数据卷即可。但有一个非常隐蔽的问题是Wiki.js在版本升级后可能会重置部分主题配置或插件兼容性。我遇到过一次升级后某个自定义主题的功能失效排查了半天最后发现是插件版本和核心版本不匹配。所以升级后不要急着验证完首页显示正常就觉得万事大吉建议把几个依赖插件的页面都点开看看确认没有功能缺失再接新版本长期使用。7. 项目上线后的使用体感与扩展建议知识库跑起来之后最大的体感变化就是“写东西的地方终于固定下来了”。我现在把家庭的一些重要信息比如设备保修单、路由器拨号账号、水电燃气开户信息、维保电话这些内容全部按照“家庭运维”这个分类整理到了Wiki.js里。以前这些东西散落在微信收藏、备忘录、短信里找的时候完全是碰运气现在按目录一搜就出来状态完全不一样。团队协作场景也值得说一下。如果你有同事或朋友一起用这个知识库Wiki.js提供了一套还算细致的权限体系。你可以给不同的人分配不同的空间和页面权限比如普通成员只能看、协作者能编辑、管理员能管理全局设置粒度比直接把所有内容公开要细得多。后续我还打算在这个基础上扩展两个东西。一是用Wiki.js的Git同步功能把整个知识库自动同步到私有Git仓库防止NAS整个硬盘损坏导致数据彻底丢失。二是在极空间上再跑一个Gitea容器把一些代码片段和运维脚本也管起来这样整个知识库加代码库都属于自己完全掌控不再依赖任何第三方平台。回到部署本身持续稳定跑了几个月PostgreSQL和Wiki.js两个容器都非常稳没有发生过崩溃或者数据错乱的情况。极空间NAS的硬件跑这两个容器也毫无压力内存长期保持在30%左右浮动。如果你手里正好有一台极空间NAS又一直在找一套靠谱的私人知识库方案我真的建议你花一个下午跟着这篇文章操作一遍。底层的逻辑理顺了后面扩展其他服务也是差不多的套路。