团队里的文档散得七零八落有人把操作流程写在聊天记录置顶里有人扔在共享盘的某个深层目录还有人干脆只存在自己电脑的某个角落。等真正要找的时候谁也记不清当初放在哪里更别提维护更新。我自己的解决方案是自建一个开源 wiki 系统把所有需要沉淀的内容都收拢到一个能搜索、能分类、有版本历史的地方。跑了一圈之后留下的是 Wiki.js——本地部署好数据自己掌控外部访问配好之后手机上随时随地都能查。这篇文章就把我在本地部署 Wiki.js 以及打通外部访问的全过程写出来包括每一步的配置细节和我真实踩过的坑。1. 为什么选 Wiki.js先解决“自建 wiki”这个选择题1.1 它到底解决了什么问题先想清楚一个问题你缺的其实不是“一个 wiki 软件”而是一套“能长期沉淀信息的机制”。平时我们记东西的方式太散了。聊天软件里的文件有过期时间共享盘里的目录一多就找不到入口本地的 Markdown 文件更是只能在一台电脑上翻。Wiki 的核心价值在于把分散的内容收拢到一个有结构的树形空间里每篇页面都能被全文搜索到每次修改都有历史记录一旦写错可以随时对比、回滚。Wiki.js 在这方面做得非常到位。它默认用 Markdown 写作上手成本几乎为零写完的内容通过分类、标签和目录树组织起来。系统内置了细粒度权限可以给整个团队开放公共区域也可以给特定成员开一个“只有项目组能看”的独立空间甚至还可以建只对自己可见的私人笔记。登录认证支持邮箱密码、OAuth2、LDAP、SAML后续想接团队现有的账号体系也不费劲。比这些功能更重要的是所有数据都握在你自己手里。内容存放在自建的数据库中图片和附件存在你指定的目录没有任何平台会突然改规则、关服务、下架你的文档。对内容比较在意、或者有长期记录需求的人来说这一点反而是选型时最优先考虑的因素。1.2 和 MediaWiki、DokuWiki、Outline 比差在哪选型阶段我对比过几个常见的开源 wiki 项目最直观的差异在于“部署代价”和“使用体验”的平衡点。项目运行环境部署难度数据存储编辑体验适合场景MediaWikiPHP MySQL较高依赖多、配置项复杂MySQL传统维基语法编辑器老旧大型公开维基站DokuWikiPHP 文件存储低文本文件编辑器简陋功能有限简单快速的小知识库OutlineNode.js PostgreSQL Redis 对象存储较高Docker Compose 排布一堆服务PostgreSQL现代但环境要求偏重有一定运维能力的团队Wiki.jsNode.js PostgreSQL/MySQL/SQLite低单进程即可运行数据库现代 Markdown 编辑器个人/中小团队知识库MediaWiki 是维基百科同款能力毋庸置疑但它的设计思路还是老一套维基语法写起来别扭后台配置也能把人绕晕。DokuWiki 轻是真轻文件即存储可功能界面都停在十年前的观感。Outline 的界面和交互我非常喜欢可它依赖 Redis、MinIO 这类组件对一台小机器来说有点重。Wiki.js 刚好卡在中间它只要 Node.js 和一个数据库就能跑部署逻辑和写一个普通后端服务没有区别同时界面现代化、权限模型清晰、API 健全内置的评论、编辑器、搜索体验也都在正常水平。对多数“想把文档管起来”的个人和中小团队来说它是成本最低、可维护性又相对好的选择。2. 部署前的技术准备版本、数据库、网络账2.1 Docker 还是 Node.js 直跑我建议先看资源Wiki.js 官方提供了两种主流部署方式容器化部署和直接跑 Node.js 服务。两条路都能用区别在于你对运行环境的掌控力和机器本身的资源。如果机器内存比较充裕2GB 以上我推荐直接用 Docker Compose 把 Wiki.js 和数据库编排到一起一条命令拉起来升级也方便。我在自己的云服务器上用的就是这种方式结构非常清晰services: db: image: postgres:15-alpine environment: POSTGRES_DB: wiki POSTGRES_USER: wikijs POSTGRES_PASSWORD: changeme volumes: - pgdata:/var/lib/postgresql/data restart: unless-stopped wiki: image: ghcr.io/requarks/wiki:latest environment: DB_TYPE: postgres DB_HOST: db DB_PORT: 5432 DB_USER: wikijs DB_PASS: changeme DB_NAME: wiki ports: - 3000:3000 depends_on: - db restart: unless-stopped volumes: pgdata:如果机器只有 512MB 甚至更小就别强行套 Docker 了镜像里跑着完整 Node 运行时再加一层叠加内存会吃紧。这种环境我建议用官方 release 包直接跑 Node 脚本一个进程就能启动后面要长期守护就交给 systemd 或者 pm2。再有就是你已经存在一个数据库集群的情况。比如公司里已经维护了一套 PostgreSQL那直接用 Node 直跑、让它连现有数据库就不会为了一个 wiki 再单独养一套数据库容器。选哪条路不是看流行而是看你手头有什么。2.2 PostgreSQL 凭什么成为默认答案Wiki.js 官方支持 PostgreSQL、MySQL、MariaDB、SQL Server 和 SQLite但官方文档和社区共识都指向 PostgreSQL。这里面有靠得住的理由。Wiki.js 的全文搜索在 PostgreSQL 上表现最好它用的是原生全文检索能力中文分词配合 PG 的文本搜索类型查文章标题和正文都很顺滑。MySQL 和 MariaDB 也能跑但部分查询的高级特性支持不完整小问题容易卡在底层数据库的差异上。SQLite 我只建议在临时体验时用——单文件数据库确实省事可一旦写入并发上来、索引文件变大查询速度下滑很明显团队场景下会很尴尬。版本上需要稍微注意。PostgreSQL 至少 9.5 以上建议直接用 14 或 15 这些还在主流维护期的版本。MySQL 8.0、MariaDB 10.2 也可以。我没有用 MySQL 跑过生产环境不过社区里反馈 MySQL 5.7 老版本在 Wiki.js 某些查询下会有兼容问题如果是存量 MySQL 5.7我建议慎重别拿生产数据去当小白鼠。2.3 外部访问的三条路线怎么选本地部署完成之后Wiki.js 默认监听 3000 端口在局域网内用http://内网IP:3000就能访问。但“外部访问”才是让文档系统真正活起来的最后一步通常有三条路线可以走局域网访问手机连同一个 WiFi直接访问内网 IP。零配置但没有公网入口人一离开这个网就抓瞎。公网 IP 直连宽带运营商分配了公网 IPv4在路由器上做端口映射再配一个 DDNS 动态域名。速度快、链路短但家用宽带对 80/443 端口的限制会导致“能连但域名不好看”的尴尬走高位端口又对记忆不友好。内网穿透通过 frp 这类工具在内网机器和一台有公网 IP 的云服务器之间建立加密隧道公网用户访问云服务器端口数据被转发到本地。链路多一跳延迟略高但稳定可控域名、证书、安全策略都集中在一台云服务器上处理。三条路里我最常用的是内网穿透。原因很实际本地机器往往没有独立公网 IP而且文档系统放在办公室或家里公网 IP 直连受网络结构限制太多。frp 是开源工具生态成熟自己的一台按量付费轻量云服务器就能跑服务端可控性远高于那些免费穿透服务。3. 部署实操全流程从服务器准备到进入管理后台3.1 准备环境Node.js 与 PostgreSQL 的版本坑以 Ubuntu 22.04 为例先把基础环境准备好。Wiki.js 对 Node.js 版本有硬性要求我用 3.x/4.x 的时候官方要求通常是 Node.js 14 以上建议直接用 18 LTS 或者更新的 LTS 版本。这里有一个我踩过的坑Ubuntu 自带的 apt 源里 Node.js 版本非常旧当年我第一台上手跑的是 Node 10启动时直接报 Unsupported Node.js version排查了半天才发现是版本问题。安装新版本 Node.js推荐走 NodeSource 仓库curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs node -v数据库方面安装 PostgreSQL 和客户端工具sudo apt install -y postgresql postgresql-contrib装完之后默认会创建一个postgres超级用户接下来在 PostgreSQL 里建一个专用的库和账号。我习惯单独为 Wiki.js 建一个用户不拿 root 级账号给它用最小权限原则在这里同样成立sudo -u postgres psql进入 psql 之后执行CREATE USER wikijs WITH PASSWORD 一个足够强壮的口令; CREATE DATABASE wiki OWNER wikijs; ALTER DATABASE wiki OWNER TO wikijs;然后退出 psql测试一下账号能不能正常登录psql -U wikijs -h 127.0.0.1 -d wiki -W这里注意连接地址填的是127.0.0.1而不是localhost因为 Wiki.js 的数据库配置里如果写 localhost部分环境会优先解析 IPv6 导致连不上。直接走 127.0.0.1 干净利落。3.2 安装 Wiki.js 与 config.yml 配置环境就绪之后下载官方 release 包。我没有走npm install -g的全局安装Wiki.js 官方推荐的方式是直接下载打包好的 release 文件里面已经包含全部依赖不用自己再跑 npm installcd /opt sudo wget https://github.com/requarks/wiki/releases/latest/download/wiki-js.tar.gz sudo tar xzf wiki-js.tar.gz sudo mv wiki /opt/wikijs cd /opt/wikijs sudo cp config.sample.yml config.yml解压之后目录里会有一个config.sample.yml复制成config.yml再编辑。配置文件格式是 YAML重点看数据库这一段port: 3000 db: type: postgres host: 127.0.0.1 port: 5432 user: wikijs pass: 你的数据库密码 db: wiki绑定的 IP 默认是所有网卡如果你是单机部署不用动它如果担心暴露面过大可以先让 Wiki.js 只监听127.0.0.1后面统一走反向代理。具体做法在bindIP字段里配置。编辑好配置后先在前台启动测试一下sudo -u www-data node server.js如果一切正常日志里会出现Listening on port 3000。确认没问题后 CtrlC 停掉然后写 systemd 服务做守护。Wiki.js 官方文档里没有强制要求用 pm2但生产运行必须有守护进程否则机器一重启服务就没了。systemd 配置如下[Unit] DescriptionWiki.js Afternetwork.target postgresql.service [Service] Typesimple WorkingDirectory/opt/wikijs ExecStart/usr/bin/node server.js Restartalways RestartSec10 Userwww-data [Install] WantedBymulti-user.target注意Userwww-data或者是运行用户一定要保证这个用户对/opt/wikijs目录有读写权限特别是后续上传图片和附件时需要写入当前目录或你指定的存储目录。sudo systemctl daemon-reload sudo systemctl enable --now wikijs sudo systemctl status wikijs到这里Wiki.js 本体已经跑起来了。3.3 首次初始化和系统设置细节浏览器打开http://服务器内网IP:3000进入初始化安装页。第一步是创建管理员账号填写邮箱和管理员密码。这里我要单独强调一个细节页面里有一个Site URL字段很多人在这一步随手填了http://192.168.1.10:3000结果后期换域名后一堆页面的图片资源路径还是按照旧 URL 拼接出现图裂、CSS 丢失等奇怪问题。所以如果你已经规划好了外部域名最好在第一次初始化时就直接填最终的公网地址比如https://wiki.example.com省得后面再折腾。初始化完成后进入管理后台先做三件事在“常规 → 站点信息”里修改站点标题和描述。在“界面语言”里切换简体中文Wiki.js 的多语言支持做得不错。在“用户/权限”里检查默认角色决定是否允许访客浏览、是否允许公开注册。关于用户注册我建议默认关闭公开注册团队成员用邀请链接或者管理员后台手动创建账号。自建系统暴露在公网上以后最容易招来的就是批量注册的垃圾账号防止这个最直接的办法就是把注册开关关上。4. 把 Wiki.js 暴露到公网穿透、反代与 HTTPS 实操4.1 没有公网 IPfrp 穿透配置全过程我这边的网络环境比较常规宽带没有公网 IPv4所以我最终采用的是 frp 内网穿透。frp 是一个开源的反向代理工具服务端跑在一台有公网 IP 的云服务器上客户端跑在本地 Wiki.js 所在机器上两者之间建立 TCP 隧道。外网用户访问云服务器端口流量通过隧道转发到本地的 3000 端口Wiki.js 根本察觉不到访问来自公网。先配置服务端云服务器。下载 frp 对应体系结构的 release 包解压后服务端配置frps.toml新版本配置格式是 TOML[common] bindPort 7000 [dashboard] webPort 7500 webUser admin webPwd 一个强口令然后在云服务器上放行 7000 和 7500 端口云安全组和系统防火墙都要放。7500 是 frp 的可视化面板端口用来观察隧道连接情况不是必须的如果不想暴露可以不开或者只允许你自己的 IP 访问。服务端跑起来之后配置客户端。客户端文件frpc.toml[common] serverAddr 你的云服务器公网IP serverPort 7000 [[proxies]] name wikijs-web type tcp localIP 127.0.0.1 localPort 3000 remotePort 8443这个配置的含义是把本地 3000 端口的服务映射到云服务器的 8443 端口。公网用户访问http://云服务器IP:8443就能直接打开本地 Wiki.js。安全上要重点提醒一句不要用 80/443 端口作为 frp 的 remotePort因为这两个端口很可能已经被云服务器上的 Nginx/Caddy 占用。更重要的是 8443 这个端口本身也不要直接暴露给用户最好再套一层反向代理让用户只访问标准的 HTTPS 端口而 Wiki.js 本身不裸奔在公网上。客户端同样建议用 systemd 守护[Unit] Descriptionfrp client Afternetwork.target [Service] Typesimple ExecStart/usr/local/bin/frpc -c /etc/frpc.toml Restartalways [Install] WantedBymulti-user.target4.2 有公网 IP端口映射 DDNS以及我为什么不常用如果你的宽带本身有公网 IP走端口映射会更直接。操作逻辑很清晰在路由器管理页找到“端口映射”或“虚拟服务器”把公网某个端口映射到内网 Wiki.js 机器的 3000 端口。如果想用标准 80/443 端口理论上更友好但家用宽带环境下这类端口经常被限制实际测试往往不通所以还是用高位端口更稳妥。动态域名可以搭配使用。阿里云、腾讯云都有免费或便宜的 DNS 解析服务路由器或内网机器上跑一个 ddns 服务把变化的公网 IP 自动更新到域名解析里这样外网访问时直接记域名不用记一长串 IP 和端口。之所以我后来没有长期用这套方案是因为几个现实问题公网 IP 一旦重拨号就变DDNS 虽然能解决域名解析但某些地区的宽带环境对公网入站连接限制较多另外端口映射是直接在路由器上开的洞Wiki.js 服务一旦有漏洞内网整个网络都在公网面前暴露。相比之下frp 方案能把入口收敛到一台云服务器上安全策略集中管理即使穿透目标被攻破攻击面也受限于这台内网机器。个人经验仅供参考如果你的网络环境稳定且可控端口映射也是一条完全可行的路。4.3 免费 HTTPSCaddy 和 Nginx 两种路径Wiki.js 自身支持配置 HTTPS 证书但实际部署中我更推荐在反向代理层终结 HTTPS原因很简单证书签发、续期、分流、缓存、安全策略都可以集中在代理层面处理Wiki.js 服务本身保持简单的 HTTP 协议即可。如果你选择用 frp 穿透推荐结构是这样的本地 Wiki.js 监听 3000 → frp 隧道映射到云服务器 8443 → 云服务器上 Caddy/Nginx 反代 8443 → 对外提供标准 443 HTTPS 访问。Caddy 是最省事的选择它内置 ACME自动申请并续期 Lets Encrypt 证书。Caddyfile 只需要一行核心配置wiki.example.com { reverse_proxy 127.0.0.1:8443 }Caddy 启动后会自动创建 HTTP→HTTPS 跳转自动申请证书并定时续期配置完基本就忘掉这一层了。如果你的云服务器上已经有 Nginx也可以继续用 Nginx手动配一下代理和证书server { listen 80; server_name wiki.example.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl; server_name wiki.example.com; ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem; client_max_body_size 100M; location / { proxy_pass http://127.0.0.1:8443; 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; } }证书申请用 acme.sh 之类的主流工具即可这里不展开。上面 Nginx 配置里有两个容易被忽略但非常关键的细节client_max_body_size决定了用户能上传多大的图片和附件默认 1M 会让你传不了稍大的截图Upgrade和Connection两个请求头是为了让 WebSocket 代理正常工作Wiki.js 的实时通知和多人协作编辑依赖 WebSocket缺了这两个头编辑器部分功能会静默失效。4.4 安全加固与访问控制的几条硬规矩外部访问打通之后安全策略必须及时跟上。我整理了这几条在自建服务上必须执行的操作不要让 Wiki.js 的 3000 端口直接暴露在公网。frp 只映射到高位端口同时 Nginx/Caddy 只监听 443。如果用户访问入口只有 443 一个端口攻击面会小很多。防火墙只放行必要端口。云服务器安全组只开 443HTTPS、7000frp 服务端、22SSH建议再配密钥登录。7500 的 frp dashboard 要么不开要么限制来源 IP。管理后台关闭公开注册管理员账号使用独立邮箱和极强口令不要用 admin 这种弱账号名。Wiki.js 后台的“安全”设置里可以开启访问日志定期检查有没有异常的 404 扫描和暴力破解尝试。安全做得越多日常使用就越不被打扰。这些习惯一旦固定下来后面维护任何自建服务都能复用同一套思路。5. 常见问题与故障排查实录5.1 页面白屏、样式丢失先查反向代理的几个响应头这大概是外部访问配好之后出现频率最高的故障通过域名打开 Wiki.js页面内容能加载但排版全乱或者干脆白屏一片而直接用内网 IP 访问却是正常的。问题通常不在 Wiki.js而在反向代理层。排除思路先打开浏览器开发者工具看请求的资源 URL 是什么。如果发现 CSS/JS 资源都在试图从某个错误域名加载那就是siteUrl配置问题——要么初始化时填了内网地址要么反代层的 Host 头没正确传递。Nginx 配置里必须保留这行proxy_set_header Host $host;没有这行Nginx 转发给 Wiki.js 的请求会丢失真实域名Wiki.js 生成资源链接时就会用默认的站点地址拼接导致引用路径错乱。同理X-Forwarded-Proto $scheme也很重要它告诉 Wiki.js 原始请求是 HTTP 还是 HTTPS缺了它 HTTPS 页面里可能混入 HTTP 资源浏览器的混合内容拦截会把页面搞残。5.2 数据库连接失败端口、鉴权、pg_hba.conf 的排查顺序启动时报数据库连接错误很多人第一反应就是“密码不对”但实际排查顺序应该是这样的用ss -lntp | grep 5432确认 PostgreSQL 是否在监听。如果监听地址只有127.0.0.1而 Wiki.js 配置的 host 是局域网 IP那必然连不上。检查账号密码。用 psql 手动连接测试能通就说明鉴权没问题。看 PostgreSQL 的pg_hba.conf。PostgreSQL 默认对本地连接用scram-sha-256或md5鉴权有些发行版默认配置会限制部分网段。如果 Wiki.js 和数据库不在同一台机器需要把对应网段的认证方式改成允许密码登录然后重启 PostgreSQL。经常见到的报错ECONNREFUSED大多是端口或监听地址的问题password authentication failed则是明明白白告诉你密码不对。按这个顺序排查比瞎猜快得多。5.3 上传图片和附件失败Nginx 限制与本地目录权限Wiki.js 默认把上传的图片和附件保存在本地目录具体位置在管理后台的“存储”设置里。上传失败时要同时怀疑两个点一是反代层的大小限制二是本地目录的写权限。Nginx 默认只允许请求体最大 1MB现在随便一张手机截图就超过这个数值。在 Nginx 配置里调大client_max_body_size我习惯设为100M。改完后先nginx -t测配置再 reload别直接重启把服务弄断了。本地目录权限问题更隐蔽。如果你手动改过存储路径或者 Wiki.js 的运行用户不是目录的属主上传时就会报 403 或者写入失败。最简单的验证方法是登录服务器手动在存储目录下touch test.txt能创建文件说明权限正常不能的话就chown -R 运行用户 存储目录解决。5.4 备份、迁移与升级的完整套路Wiki.js 的数据分两部分一部分在数据库里包括页面内容、用户、权限设置、版本历史另一部分是上传的图片和附件存在本地存储目录。备份时两者都不能漏。数据库备份用 PostgreSQL 自带的逻辑备份pg_dump -U wikijs -h 127.0.0.1 -d wiki -F c -f wiki-$(date %Y%m%d).dump附件目录直接打包归档tar czf wiki-data-$(date %Y%m%d).tar.gz /opt/wikijs/data恢复时先创建空的wiki数据库和wikijs用户再pg_restore -d wiki wiki-xxx.dump然后把附件目录解压回去重启服务即可。升级时不要图省事直接覆盖文件。最稳妥的流程是先备份配置文件和数据库 → 下载新版本 release 到临时目录 → 比对config.yml的差异 → 替换老目录 → 重启并检查日志。Wiki.js 主版本升级时可能会有数据库迁移任务首次启动需要多一点耐心不要看到启动慢就断定卡死。最后说两句从本地部署到公网访问Wiki.js 这套链路我前前后后维护了大半年从一开始的配置踩坑到后来把备份、反代、安全策略都理顺最大的感受是这套系统技术上没什么不可逾越的门槛真正难的反而是一开始想清楚“内容怎么组织、谁来维护、数据怎么备份”这三件事。工具选对了文档管理就能从“随手记”变成“可持续的资产”。如果你也在纠结文档散落的问题不妨按这条路试一遍先在小范围用起来再逐步把团队的规范沉淀进去价值会远比想象中的大。