半年前我接手了一个五人技术小组的文档维护第一件事就是把散落在聊天记录、Excel、个人备忘录里的知识收拢起来。试了几套方案之后最终定在 Wiki.js 上——开源、界面清爽、轻量、数据能完全握在自己手里而且支持本地部署。后来我给它打通了外部访问整条链路里踩过的坑不少。今天就围绕“本地部署开源 wiki 软件 Wiki.js 并实现外部访问”这条主线把选型、部署、配置、开放外网访问的完整过程一次讲透。如果你正准备给团队或个人搭一套自托管知识库这篇文章可以直接照着抄。我会按“先想清楚需求、再选型、然后上手部署、接着完善配置、最后解决外网访问”的顺序来写。没接触过 Docker 的朋友不用慌每一步我都会给出完整命令和解释已经熟手的朋友可以直接跳到第 5 节看外部访问部分的实际经验。1. 为什么是 Wiki.js先想清楚要解决什么问题1.1 自建 wiki 的核心需求拆解先别急着装软件。任何自托管项目第一步都是把需求拆干净不然很容易装了一堆服务最后真正用的还是原来的聊天记录。我当时做这套本地部署核心诉求只有四条。第一是数据自主可控文档数据库和附件必须放在自己服务器上不能因为某个云服务调整策略就导致知识库搬家。第二是支持 Markdown 写作这是技术团队最习惯的格式迁移成本最低从旧笔记导出时几乎不需要重新排版。第三是部署和运维负担不能太大不能每天花大量时间维护这个系统本身我宁愿把时间花在写文档上。第四是需要能从外部访问以后出差、居家、在客户现场查资料都能打开页面而不是回到办公室才能翻文档。这四条诉求基本把方案范围圈死了。云笔记直接排除SaaS 知识库也大部分排除剩下的就是开源且支持自托管的 wiki 系统。当时我也把“本地部署 deepseek”这类 AI 蒸馏方案放在旁边犹豫过但知识库和模型检索是两回事wiki 的核心始终是清晰的文档结构和权限管理不是模型能力。所以最终还是老老实实选一个成熟的 wiki 引擎。1.2 主流 wiki 方案选型对比市场上常见的开源 wiki 方案其实不少我在选型时把主流方案都过了一遍。这里直接给一张对照表效率最高。方案技术栈部署难度界面体验权限管理一句话评价Wiki.jsNode.js 数据库中低现代细粒度体验好、生态活跃适合轻量团队BookStackPHP Laravel中简洁中适合偏爱层次化文档的用户MediaWikiPHP中高传统中功能全但界面老维护偏重DokuWikiPHP中低朴素中老牌轻量适合单文件存储场景OutlineNode.js React中高现代中体验接近 Notion但部署链路更长ConfluenceJava中高现代强功能强大但臃肿商用授权贵当时把 Wiki.js 列为第一候选理由很直接。它的前端体验在现代开源 wiki 里算是第一梯队搜索是实时索引的文档支持多语言和细粒度权限而且基于 Git 的备份机制非常适合技术团队。Outline 其实也不错但它早期还强调依赖较多外部服务部署链路比 Wiki.js 长。BookStack 在分类组织上更贴近传统目录但没有 Wiki.js 的灵活页面树和多语言能力。选 Wiki.js 还有一个现实原因整个服务主要依赖一个应用容器数据放在一个独立的数据库容器里升级就是重新拉镜像运维压力非常小。这个特点在“必须外部访问、要长期运行”的场景里特别有价值意味着可用性管理可以做得非常简单。1.3 Node.js 生态带来的扩展空间这一点值得单独说。Wiki.js 是一个 Node.js 应用页面内容以 Markdown 存储配合插件系统可以接入评论、图表、代码高亮、公式渲染等能力。接入 Git 之后每次编辑都会自动提交到远端仓库相当于给文档做了版本管线和异地备份这对团队协作是很大的加分项。技术团队通常会在这个基础上继续扩展比如接入 OpenID 单点登录让公司账号直接登录或者用 API 把 wiki 内容同步到内部系统。这些能力不是刚部署时需要的但选型时如果框架生态太封闭后面会非常痛苦。Wiki.js 的模块化设计在这类需求上表现不错我后面在配置章节也会提到一些具体用法。2. 部署前的准备硬件、Docker 与数据库选型2.1 硬件要求没有想象中高Wiki.js 对硬件的需求并不苛刻。官方文档给了最低配置实际操作下来我可以给一个更贴近真实情况的参考单机部署时1 核 CPU、1GB 内存基本能跑起来但考虑到 PostgreSQL 同时运行在同一台机器上内存建议至少 2GB。磁盘方面系统本体和依赖占用不到 200MB真要长期积累文档和附件建议至少预备 20GB 以上空间并且提前规划备份存储位置。如果是给几十人以上的团队做并发访问CPU 和内存可以适度上调。我自己是在一台 4 核 8GB 的旧服务器上跑的同时挂了 Wiki.js、PostgreSQL 和一个反向代理平时负载很低内存占用在 1.2GB 左右。这个表现已经足够应付绝大多数中小团队的文档场景。所以不用为配置焦虑手头有台旧电脑都能用。2.2 Docker 和 Docker Compose快捷部署的前提安装 Docker 是让 Wiki.js 落地最快的一条路径。Wiki.js 官方镜像在 Docker Hub 和 GHCR 都有发布用 Docker Compose 可以把应用和数据库一起编排启动、重启、升级都是几条命令的事。对于还不熟悉 Docker 的朋友我简单解释一下它在本文中的作用。Docker 相当于给应用提供了一个隔离运行环境应用依赖的 Node.js 版本、系统库、配置都被打包进镜像里宿主机只需要有 Docker 引擎就能运行。Compose 则是多容器编排工具用一份 YAML 文件描述“Wiki.js 容器”和“PostgreSQL 容器”启动时按声明好的依赖关系一起拉起服务。如果不想用 Docker官方也提供基于 Node.js 的源码安装方式需要自己装 Node.js 和数据库。但我不建议在自托管初期走这条路。源码安装要处理 Node 版本兼容、进程守护、日志管理这些琐碎问题容器化把这些都抽象掉了。把复杂度交给 Docker省下来的时间正好可以拿去做权限和备份配置。2.3 数据库选型SQLite 能用但不推荐当长期方案Wiki.js 支持 PostgreSQL、MySQL、MariaDB、SQL Server 和 SQLite。很多人第一次部署图省事直接用 SQLite 单文件模式确实能跑起来但对大多数实际用途来说我不推荐把它作为长期方案。原因有三点。一是并发写入能力有限多人同时编辑时SQLite 的锁机制容易造成页面卡顿或偶发写入失败。二是备份方式比较受限虽然 Wiki.js 自带内容 Git 备份但数据库本身的备份最好还是依赖数据库的能力SQLite 的备份方式没有 PostgreSQL 成熟。三是外部访问后并发场景增加数据库压力会更明显SQLite 的瓶颈会更快暴露。我的建议是直接用 PostgreSQL。它成熟、生态好与 Wiki.js 的配合也最顺畅社区里遇到问题时答案也最多。MySQL 也可以只是如果用 MySQL 8 要注意数据库驱动配置不然查询时可能出现字符集排序方面的小问题我实际遇到过中文排序不符合预期的状况排查起来比较费时。3. 详细部署步骤从空目录到可访问的 wiki3.1 用 Docker Compose 一次性拉起服务整个部署过程可以压缩到十分钟左右。先在服务器或者电脑上创建一个工作目录比如~/wiki把所有配置文件集中管理后续升级、备份、迁移都从这里走。version: 3 services: db: image: postgres:14-alpine container_name: wikijs-db environment: POSTGRES_DB: wiki POSTGRES_USER: wikijs POSTGRES_PASSWORD: wikijs-pass volumes: - db-data:/var/lib/postgresql/data restart: unless-stopped wiki: image: ghcr.io/requarks/wiki:2 container_name: wikijs depends_on: - db environment: DB_TYPE: postgres DB_HOST: db DB_PORT: 5432 DB_NAME: wiki DB_USER: wikijs DB_PASS: wikijs-pass ports: - 3000:3000 volumes: - wiki-data:/wiki/data restart: unless-stopped volumes: db-data: wiki-data:这里有几个细节值得专门解释。PostgreSQL 镜像用的 14-alpine这是体积较小的官方镜像Wiki.js 2.x 对 PostgreSQL 14 的支持非常成熟而 16 在一些数据库驱动上需要额外配置所以选 14 是最省心的。数据库密码我没有用特殊字符避免环境变量解析时出现转义问题生产环境里更稳妥的做法是把密码放进.env文件中管理不要直接写进仓库。启动只需要一条命令。在~/wiki目录下执行cd ~/wiki docker compose up -d如果你还在用旧版 Docker也可以执行docker-compose up -d。第一次启动会拉取两个镜像等待时间取决于网络状况。启动完成后用docker ps检查两个容器状态然后访问http://服务器IP:3000。3.2 初始化向导创建管理员与第一篇文章首次访问 Wiki.js 会进入安装向导。第一步设置管理员邮箱和密码第二步向导会自动检测到已经配置好的 PostgreSQL不需要手动输入第三步创建第一个主页建议命名为 Home 或者直接用默认首页模板。完成之后 Wiki.js 会重新加载进入正常登录界面。这里有两个常见的坑。第一个是密码复杂度Wiki.js 默认要求密码达到一定强度如果设置太简单前端会直接提醒但有些版本提示文案不明显容易让人误以为页面没反应。第二个是安装向导中途报错如果数据库连接配置不对浏览器会停留在安装页面并提示连接失败。这时候回到 docker-compose 文件检查数据库的POSTGRES_PASSWORD和 Wiki.js 的DB_PASS是否一致基本都能解决。初始化完成后建议先把“主页”调整成真正的内容入口。比如放一个团队文档导航把“快速上手指南”“API 接口约定”“运维手册”几个核心栏目做成链接卡片。Wiki.js 默认支持卡片式主页区块我在第 4 节会具体讲怎么配置。3.3 端口与防火墙基础配置Wiki.js 默认监听 3000 端口。在局域网内部署时要确保这台服务器的防火墙规则允许 3000 端口访问。如果用的是云服务器还要在安全组里放行 TCP 3000如果用的是家里的物理设备要注意路由器上有没有开启 AP 隔离有些路由器默认开了访客隔离会把设备之间的互访挡掉这也是外部访问方案里一个频率不低的乌龙。在生产环境里我通常不会让 3000 端口直接暴露到公网。正确做法是把 80/443 留给反向代理由反向代理转发到内部 3000 端口。这样既能统一管理证书也能隐藏内部服务细节。这个思路在外部访问部分会详细展开但先在这里埋个伏笔等你配置时自然会理解为什么要这样分层。4. 部署完之后的配置权限、搜索、主题与备份很多文章到“安装完成”就截然而止但实际使用中让我真正觉得这套系统“好用”的恰恰是安装之后的配置。4.1 权限体系给不同角色的成员划清边界Wiki.js 的权限模型比很多开源 wiki 要细。默认角色有管理员、作者、编辑者、评论者、查看者等。管理员拥有全部权限作者可以创建和修改页面编辑者和评论者的权限更窄查看者只能读取。还可以自定义角色设置精确到页面树的访问范围。我的建议是不要在一开始就设计复杂的角色矩阵除非团队规模真的很大。多数团队用三档就够管理员负责全局配置、作者负责写文档、查看者负责阅读。权限配置入口在“管理后台-用户与安全-角色”里操作方式很直观勾选对应权限即可。比较需要留意的是“区域权限”概念。Wiki.js 允许把权限绑定到某个区域也就是页面路径下比如/技术/后端这个区域只有后端成员能写前端成员可以看但改不了。这个机制很灵活但理解成本略高。我的经验是先不启用区域权限等文档体系跑顺了确实有跨团队隔离需求时再开启否则配置复杂度会干扰日常写作。4.2 内容组织、搜索与多语言配置Wiki.js 的页面组织方式是树状结构类似文件系统导航栏默认按树展开。配置导航时可以拖拽调整顺序也可以设置“隐藏子页面”“折叠显示”等选项。内容多了之后我习惯把导航控制在三层以内超过三层的页面在导航里只展示两级第三级靠搜索找否则侧边栏看起来非常臃肿。搜索这块Wiki.js 默认是内置全文索引页面编辑后增量更新。如果使用 PostgreSQL 作为数据库在管理后台可以启用 PostgreSQL 全文搜索效果更稳。注意启用了全文搜索之后搜索结果按相关度排序旧数据可能需要重建索引才能保证准确重建索引在数据库量不大的情况下几乎瞬间完成。多语言方面Wiki.js 支持系统界面多语言页面内容也支持多语言版本适合做国际化团队的知识库。但单语文档场景我不推荐开启开启后导航会多出语言切换逻辑维护成本上升对团队没实际收益。主题方面Wiki.js 自带多套主题常见的有 Default、Tau、Cyborg 等在“管理后台-外观”里切换即可一般不需要额外写 CSS。Tau 主题是我实际使用下来排版最顺眼的导航和内容区比例比较舒服代码高亮效果也是内置的写接口文档时体验很好。4.3 备份策略让 Git 和自动备份形成双保险这一点必须单独强调。本地部署意味着所有数据都在自己手里安全感和风险是并存的——机器坏了、硬盘损坏、误操作都会导致知识库丢失。Wiki.js 的备份机制是我认为它优于很多同类项目的地方。第一个机制是 Git 备份。在“管理后台-备份-存储策略”里可以配置 Git 存储Wiki.js 会把每次页面变更以 Git 提交的方式同步到远程仓库。这个机制带来的好处是文档版本历史和代码仓库一致任何人误修改都可以直接git log回溯。我自己的习惯是给 wiki 单独建一个私有 Git 仓库配置好提交频率几乎零运维成本。第二个机制是自动备份。Wiki.js 支持把备份文件定期推送到本地目录、SFTP、S3 或 Azure Blob。如果你环境里有 NAS直接把备份推到 NAS 的目录是最省心的做法。备份频率我建议每天一次保留最近 30 个文件即可。配合 Git 备份基本可以做到双保险。真遇到服务器硬盘损坏从 Git 仓库恢复内容再从 NAS 恢复数据库整套流程可以控制在半小时内。5. 实现外部访问从局域网到公网的完整链路这是整篇文章的重头戏。很多人部署完局域网版就算了但“外部访问”才是让知识库真正发挥价值的关键一步。它意味着你不再依赖固定工位出差途中、客户现场、居家办公时都能打开同一个页面查资料、补文档都不中断。注意这块要结合你自己的网络条件来选方案不是每个人都需要公网 IP。5.1 先想清楚入口方式三种常见路径实现外部访问本质上要回答两个问题外部设备怎么找到你的服务器外部设备怎么安全地访问你的服务按照网络条件不同常见入口方式可以分成三类。有公网 IP且允许入站时最正统的方案是路由器端口转发配 DDNS再加上反向代理和 HTTPS。没有公网 IP但有一台公网服务器时可以用 frp 这类内网穿透工具把内网服务映射到公网服务器的端口上。不要求公网暴露、只要求内外网组网时用 Tailscale 或 ZeroTier 这类异地组网工具把外部设备接入虚拟内网直接访问体验接近局域网。这三条路可以根据条件选也可以组合使用。我自己是在有公网 IP 的路由器环境中部署的先用端口转发把 3000 暴露到公网后来加了 DDNS 和 Caddy 反向代理体验明显上了一个档次。5.2 公网 IP 方案DDNS、端口转发与反向代理如果家里或公司网络具备公网 IP并且路由器支持端口转发这条路最自然。具体分三步走。第一步是路由器端口转发。在路由器管理界面找到“端口转发”或“虚拟服务器”功能把外部端口 443或自定义端口转发到内网运行 Wiki.js 的机器 IP 的 3000 端口。这里最需要注意的是目标 IP 必须是这台服务器在局域网里的固定 IP最好是提前给机器设置 DHCP 静态分配避免重启后 IP 变了导致转发失效。第二步是配置 DDNS。很多路由器自带 DDNS 客户端绑定一个域名这样即使公网 IP 变化也能通过域名访问。如果没有域名也可以先通过 IP 访问但长期来看域名加 HTTPS 是必须的。我用的是阿里云域名加路由器自带 DDNS实测下来只要路由器不重启解析基本不会掉。第三步是配置反向代理。我在这里强烈推荐 Caddy它的配置文件非常简洁几行就能做到强制 HTTPS。用一段最短配置示例wiki.example.com { reverse_proxy 192.168.1.100:3000 }Caddy 会自动申请和续期 Lets Encrypt 证书省去了手动管理证书的麻烦。相比之下Nginx 配置更繁琐但控制能力更强如果你已经有 Nginx 基础继续用 Nginx 也完全可以。反向代理的另一个好处是以后如果要把 Wiki.js 从 3000 端口搬到别的端口只需要改代理配置外部访问地址不变对使用者完全透明。配置完成后用浏览器访问https://你的域名能看到登录页就说明链路通了。这一套流程下来最大的好处是搜藏夹、书签、文档内引用指向的都是固定域名不会因为 IP 变动而失效。5.3 没有公网 IP 时frp 内网穿透与异地组网没有公网 IP 的情况其实很常见。如果手头有一台公网服务器frp 是当前生态里特别成熟的方案。frp 分服务端和客户端服务端部署在公网服务器上客户端部署在跑 Wiki.js 的局域网机器上通过两者建立隧道把内网 3000 端口代理到公网服务器端口。frp 配置不复杂。服务端配置文件设置一个 bindPort客户端配置文件声明一个代理把本地 3000 端口映射到服务端的指定端口。启动两个进程后外部访问公网服务器IP:端口就能连到内网服务。注意 frp 客户端要配置成服务方式运行不然终端一关隧道就断了。除了 frp还有 Cloudflare Tunnel 这类方案。如果你有 Cloudflare 账号并在域名上接入了托管可以在内网机器上运行cloudflared tunnel把本地服务映射到 Cloudflare 的边缘网络由 Cloudflare 自动处理证书和安全策略。这个方案免去了公网服务器和手动证书管理但对网络环境和可定制性不如 frp国内网络环境下的实际体验需要自己测试。最后一种是更省心的异地组网方案比如 Tailscale 或 ZeroTier。它们把多台设备组成一个虚拟局域网外部设备安装客户端并加入同一个账号组后就能通过虚拟内网 IP 直接访问 Wiki.js。这种方案对没有公网服务器的个人用户最友好但需要访问者设备也安装客户端适合小团队内部使用不适合面向互联网的公开知识库。不管选哪条路安全都是必须考虑的。暴露到公网的服务越多被扫描和攻击的风险就越高。建议至少做到三点一是不要使用默认管理员账号密码要足够复杂二是优先启用 HTTPS三是定期检查容器日志和服务状态发现异常及时处理。6. 常见问题与排查这部分是我把这套系统长期跑下来的经验总结。很多问题其实不是“看不懂文档”而是文档里根本没有写清楚只有真正遇到过才会明白。6.1 初始化失败和数据库连接异常最典型的问题是安装向导一直停在“正在连接数据库”或者直接提示连接失败。排查顺序可以先看几个地方。第一检查两个容器是否都正常运行执行docker ps看wikijs和wikijs-db的状态。如果 db 容器没有成功启动多半是环境变量配置问题重点检查 PostgreSQL 镜像的POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD是否与 Wiki.js 侧的DB_NAME、DB_USER、DB_PASS完全对应。第二查看 Wiki.js 容器日志执行docker logs wikijs。日志里如果出现ECONNREFUSED或password authentication failed基本定位在数据库连接层。此时先确认数据库容器已经处于健康状态再用docker exec -it进入数据库容器执行一条简单查询测试数据库是否正常响应。如果用的是 MySQL注意检查驱动和连接方式官方文档对 MySQL 配置有专门说明必须注意字符集设置否则中文内容可能出现乱码。另外提醒一句有些人为了省资源只跑 SQLite初始化向导确实没问题但跑了一段时间后首页加载越来越慢偶尔报数据库锁定错误。这通常就是 SQLite 在高并发下的瓶颈。真遇到这种问题建议一次性换成 PostgreSQL数据库迁移用 Wiki.js 的备份恢复功能就能完成。6.2 页面打不开、白屏与样式丢失页面打开是白屏是自托管服务里很让人头疼的问题。遇到白屏时先按 F12 打开浏览器开发者工具看“控制台”和“网络”标签页。常见原因有三个前端资源加载失败、浏览器缓存冲突、反向代理配置错误。如果是通过反向代理访问时白屏最可能是 WebSocket 和静态资源路径配置出了问题。Wiki.js 的实时编辑和通知依赖 WebSocket反向代理需要支持 WebSocket 升级。Caddy 默认支持Nginx 则需要额外配置几行proxy_set_header Upgrade和Connection。静态资源问题通常是因为代理没有正确传递Host请求头导致资源请求跳到了错误地址在 Nginx 里强制设置proxy_set_header Host $host;基本能解决。有时候浏览器强缓存也会造成旧版页面资源加载错误。更新完版本后遇到白屏先试试强制刷新CtrlF5或者开无痕窗口访问把缓存因素排除掉再继续排查反向代理。6.3 外部访问层面的常见问题外部访问不通排查链路里的每一环都可能。我把踩过的坑整理成一张速查表能省很多排查时间。现象可能原因处理方式局域网能访问外部不能访问路由器端口转发没生效检查内外端口映射是否写反确认服务器内网 IP 没有变更外网能打开但加载很慢带宽不足或代理节点转发效率低查看反向代理带宽占用考虑增加缓存策略手机 4G/5G 下打不开网络运营商策略对非标准端口有限制配置公网标准端口或改用 HTTPS 标准端口访问域名能解析但访问异常DDNS 更新延迟或证书过期检查 DDNS 状态访问证书管理面板确认续期情况外部访问时被安全设备拦截遭遇恶意扫描或触发防火墙策略启用防火墙限流、更换访问端口开启身份验证和强制 HTTPS这里最值得提醒的是外部访问一旦开放就一定会被扫描器盯上。不要用弱密码不要暴露管理后台给不相关的人看最好开启二步验证。如果只是小团队使用还可以在反向代理层加白名单把访问来源限制在固定 IP 或网段内。安全不是可选项是长期运行的前提。6.4 升级与版本管理Wiki.js 的升级其实比想象中简单但很多人踩坑是因为忽略了备份。我的升级流程是先通过管理后台手动触发一次备份然后进入部署目录执行docker compose pull docker compose up -d。镜像更新后容器会自动重建数据卷不受影响。如果新版本启动失败用docker compose logs wiki查看报错必要时回滚到上一版本的镜像 tag 就行。有一点必须注意Wiki.js 2.x 的数据库结构在跨小版本升级时会自动执行迁移这个迁移过程需要数据库处于健康状态。升级前尽量停止用户写入操作升级过程中不要强制重启数据库容器。迁移期间控制台会打印大量日志看到migration completed才算真正结束。很多人不管三七二十一直接重启结果数据库结构迁移到一半后续启动就一直怪怪的。7. 个人体会自建 wiki 是门槛最低的自托管实践7.1 我从运行中摸到的几条经验自建 wiki 虽然看似只是装个软件但它本身就是一个很好的自托管练手项目需要选型、部署、配置、备份、开放外网访问几乎覆盖了自托管服务运维的完整链路。做完这一套你对 Docker、数据库、反向代理、证书、内网穿透的理解都会上一个台阶。我有几个具体建议。第一从一开始就考虑“如何恢复”而不是只考虑“如何部署”——把 Git 备份和自动备份配置好再对外开放服务是成本最低的安全保障。第二对外暴露前先做一轮基础加固设置强密码、启用强制 HTTPS、关掉不用的默认端口。第三不要把文档结构设计得太复杂树状目录三层以内最舒服等团队习惯了再逐步微调。7.2 后续还能扩展什么如果你已经跑通这套系统下一步可以试试把评论模块接进来或者接入 OpenID 登录让团队统一账号体系。还可以用 API 把 wiki 内容和内部系统打通比如在新项目启动时自动生成文档目录或者把发布流程中产生的变更记录自动归档到 wiki。自托管这条路一旦走通你会发现能扩展的服务远不止一个 wiki。