Wiki.js安装为何要求填写公网URL？本地测试及nginx反代该如何配置？

公网URL字段的实际作用 #

• 该字段是Wiki.js实例的全局基准访问地址，不会随访问请求的来源动态变化
• 实际影响的功能场景包括：生成站内所有跳转链接、附件资源的访问路径、邮件通知里的跳转地址、第三方OAuth登录的回调URL、Webhook的回调地址
• 字段填写错误会直接导致链接跳转失效、静态资源加载404、第三方登录失败等问题，并非可选的冗余配置项

纯本地测试场景的配置方法 #

• 没有公网访问需求时，不需要填写示例中的公网域名，直接填写你实际访问Wiki.js的完整本地地址即可
• 本地直接通过3000端口访问的场景，填写http://localhost:3000
• 如果是局域网内通过其他设备访问本机的Wiki.js，就替换成本机的局域网IP地址，比如http://192.168.3.20:3000
• 注意一定要带对应协议前缀（http/https），不要只填域名或IP，避免Wiki.js错误强制跳转HTTPS导致页面打不开

Nginx反向代理场景的配置方案 #

Wiki.js侧的URL填写规则 #

• 填写用户最终访问该Wiki服务时在浏览器输入的完整地址，而非Wiki.js进程本身监听的本机地址
• 举例：如果Nginx将域名wiki.yourdomain.com的请求转发到本机127.0.0.1:3000的Wiki.js服务，无论Wiki.js是否对外开放3000端口，这里都直接填写https://wiki.yourdomain.com
• 如果没有配置域名，直接通过服务器公网IP加端口访问，就原样填写对应的完整访问地址，比如http://112.34.56.78:8080
• 如果Wiki.js部署在Nginx的子路径下（比如http://yourdomain.com/wiki），填写的URL也要带上完整的子路径部分

Nginx侧的配套配置要求 #

• 需要在反向代理规则中传递正确的请求头，让Wiki.js识别真实的访问来源，核心需要配置的项包括：
  • 原样传递Host请求头，不要让Nginx自动改写为后端服务的本机地址
  • 传递X-Real-IP请求头，记录真实客户端IP
  • 传递X-Forwarded-For请求头，保留完整的代理链路IP信息
  • 传递X-Forwarded-Proto请求头，告知Wiki.js前端请求使用的是HTTP还是HTTPS协议
• 最小化的代理配置示例：

server {
    listen 80;
    server_name wiki.yourdomain.com; # 和Wiki.js中填写的基准地址保持一致
    location / {
        proxy_pass http://127.0.0.1:3000; # 仅监听本机端口，无需对外暴露
        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;
    }
}

• 注意如果是通过HTTPS对外提供服务，需要先在Nginx侧配置好SSL证书，再将X-Forwarded-Proto的值设置为$scheme，保证Wiki.js生成的链接都是HTTPS协议

内容的提问来源于stack exchange，提问作者Power_tile