Logo 📚 Digital Library

Trilium 分享

Trilium 分享 — OpenResty / Nginx 反向代理 配置与说明#

本文档介绍如何使用 OpenResty / Nginx 将外网域名 https://srv.isrv.cn 映射到本地 Trilium 分享服务 http://127.0.0.1:40172/share/...。要求为：

  • 根地址 https://srv.isrv.cn 映射到 http://127.0.0.1:40172/share/server（主页特例）
  • 其它任意路径 https://srv.isrv.cn/<path> 映射到 http://127.0.0.1:40172/share/<path>（自动前缀 /share）

目录#

  1. 配置目的与需求
  2. 完整可用的 OpenResty / Nginx 配置
  3. 配置详解（逐行说明）
  4. 变体与常见场景
  5. 测试方法与验证步骤
  6. 常见问题与排查建议
  7. 安全与性能建议
  8. 部署与运维小贴士

1. 配置目的与需求#

目标是只将 Trilium 的分享功能暴露到互联网，同时保持 Trilium 的管理界面仅在内网或 VPN 中访问。你要求的映射规则是：

  • 主页(/) 特殊映射到 /share/server
  • 其它任何路径都在外部路径前自动加上 /share 转发到本地 Trilium

这能保证：

  • 浏览器看到的 URL 友好（无需显式包含 /share）
  • Trilium 分享链接（包括静态资源、图片、脚本）能正确被后端服务处理

2. 完整可用的 OpenResty / Nginx 配置#

server {
    listen 443 ssl http2;
    server_name srv.isrv.cn;

    ssl_certificate     /www/sites/p1.isrv.cn/ssl/fullchain.pem;
    ssl_certificate_key /www/sites/p1.isrv.cn/ssl/privkey.pem;

    # 主页（精确匹配） → /share/server
    location = / {
        proxy_pass http://127.0.0.1:40172/share/server;
        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_http_version 1.1;
        proxy_set_header Connection "";
    }

    # 其它所有请求 → /share<原始请求 URI>
    location / {
        # 将外部请求 URI 透传到后端，但在最前面加上 /share
        proxy_pass http://127.0.0.1:40172/share$request_uri;
        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_http_version 1.1;
        proxy_set_header Connection "";
    }
}

将上面的 ssl_certificate 与 ssl_certificate_key 路径替换为你实际使用的证书文件路径。若在本机使用 HTTP（不推荐），将 listen 改为 80 并移除 ssl_* 行。

3. 配置详解（逐行说明）#

  • listen 443 ssl http2;：监听 443（HTTPS），启用 HTTP/2 提升并发性能。
  • server_name srv.isrv.cn;：匹配域名。
  • ssl_certificate / ssl_certificate_key：SSL 证书与私钥位置。

location = /（精确匹配根路径）#

  • location = /：仅在请求路径精确为 / 时匹配（不包含 /foo）。
  • proxy_pass http://127.0.0.1:40172/share/server;：把根路径代理到后端的 /share/server（你的 Trilium 分享主页）。
  • proxy_set_header Host $host;：将原始主机名传给后端（有些应用用来生成 URL）。
  • X-Forwarded-* 头：保留客户端 IP 与原始协议，便于后端日志或处理。
  • proxy_http_version 1.1 与 proxy_set_header Connection ""：改善长连接与 WebSocket/事件流等场景兼容性。

location /（所有其它路径）#

  • proxy_pass http://127.0.0.1:40172/share$request_uri;：关键点，将原始请求 URI（包含路径与查询字符串）追加到 /share 之后发往后端。例如：
    • 外部 /a/b?x=1 → 内部 http://127.0.0.1:40172/share/a/b?x=1
  • 通过这种写法，可以透明代理静态资源、api 路径与带参数的分享链接。

4. 变体与常见场景#

4.1 后端只在 /share/server 下工作#

如果你的后端只能处理 /share/server/... 而不是 /share/...，可以改写 proxy_pass：

location / {
    proxy_pass http://127.0.0.1:40172/share/server$request_uri;
}

这会把 /foo 转到 /share/server/foo。

4.2 保持 Host 为后端原始（不推荐）#

如果需要把 Host 设为后端的主机（例如后端严格校验 Host），可以把 proxy_set_header Host 改为 127.0.0.1:40172。但通常保留原 Host 更有利于生成外部链接。

4.3 支持 WebSocket / SSE#

Trilium 的分享功能大部分是普通 HTTP，但若后端使用 WebSocket/SSE，确保 proxy_http_version 1.1; 与 proxy_set_header Connection ""; 已设置，且没有 proxy_buffering on 强制缓冲影响实时性。

5. 测试方法与验证步骤#

  1. 重载配置（有修改配置后）

    sudo nginx -t && sudo systemctl reload nginx

  2. 测试首页

    curl -I https://srv.isrv.cn/
# 或者
curl -v https://srv.isrv.cn/
    • 期望返回 200，且页面内容为 Trilium 分享主页（或跳转后显示）。

  3. 测试其它路径

    curl -v https://srv.isrv.cn/some-share-id
    • 期望代理到 http://127.0.0.1:40172/share/some-share-id 并返回正常内容。
  4. 检查静态资源
    • 在浏览器打开一个分享页面，观察开发者工具（Network），确认 CSS/JS/图片请求返回 200 且路径为 /share/...（代理后端）。
  5. 查看 Nginx 与 后端 日志
    • Nginx: /var/log/nginx/access.log 与 error.log
    • Trilium: 你部署 Trilium 的容器/服务日志，确认没有 404/500 错误。

6. 常见问题与排查建议#

  • 样式/脚本加载失败：通常因为后端生成资源链接时使用了不带 /share 的绝对路径，或代理没有正确转发查询字符串。使用 proxy_pass ...$request_uri 可保留查询字符串。

  • 302 重定向到错误路径：若后端返回重定向（Location 头指向 /share/... 之外），检查后端生成 URL 的逻辑。proxy_redirect 可以用来重写 Location 头：

    proxy_redirect http://127.0.0.1:40172/share/ https://srv.isrv.cn/;

    但通常保留 Host 并让后端生成正确的外部 URL 更好。

  • 静态资源返回 404：确认后端应用实际提供的路径（是否确实在 /share/ 下），并检查 Nginx 的 error_log 获取精确信息。

7. 安全与性能建议#

  • 仅暴露分享服务：你的配置已经将 / 与 /any 映射到分享功能，未暴露 Trilium 管理界面（前提是后端管理界面不在 /share 下）。若管理界面与分享共存于同一路径，请使用更严格的访问控制（IP 白名单、VPN）。

  • 强制 HTTPS：如果你还监听 80 端口，建议强制重定向到 HTTPS：

    server {
  listen 80;
  server_name srv.isrv.cn;
  return 301 https://$host$request_uri;
}
  • 限流 / 防暴力：可以用 limit_req、limit_conn 或 OpenResty Lua 插件实现简单限流，防止恶意扫链或暴力请求。
  • 缓存静态资源：对 /share/assets/* 等静态资源设置 expires 或 cache-control 可提高性能（注意动态分享内容不要缓存）。
  • 安全头：可以添加 X-Frame-Options、X-Content-Type-Options 等头部提升浏览器安全性。

8. 部署与运维小贴士#

  • 在修改配置前备份原 nginx 配置文件。
  • 使用 nginx -t 检查语法再 reload。
  • 若使用 Docker 容器运行 Trilium，请确认容器监听 127.0.0.1:40172 或内部网络能被主机访问；若在容器内监听 0.0.0.0 且端口映射合理，OpenResty 能访问到服务。
  • 定期检查证书有效期（使用 acme.sh 或 certbot 自动续期）。

9. HTTP 自动跳转 HTTPS（301 重定向）#

在你的主 HTTPS 配置之外，建议额外添加一个 80 端口的 server 区块，实现 http → https 自动跳转：

server {
    listen 80;
    server_name srv.isrv.cn;

    # 访问 http://srv.isrv.cn 自动跳转到 https://srv.isrv.cn
    return 301 https://$host$request_uri;
}

这是强制 HTTPS 的标准写法，避免明文访问。

附：常用命令#

# 检查 nginx 配置
sudo nginx -t

# 重新加载 nginx（不重启进程）
sudo systemctl reload nginx

# 查看最近 200 条 nginx 访问日志
tail -n 200 /var/log/nginx/access.log

# 查看最近 200 条 nginx 错误日志
tail -n 200 /var/log/nginx/error.log