当前位置：首页 > news >正文

Portarium：自托管服务统一入口与反向代理部署实战

news 2026/4/27 14:25:07

1. 项目概述与核心价值

最近在折腾个人服务器和家庭网络时，发现一个痛点：手头管理着好几台不同用途的服务器，有的是跑Web服务的，有的是做数据库的，还有的是内网穿透的。每次想看看某个服务的状态，或者临时改个配置，都得先查IP、记端口，再打开浏览器输入一长串地址，非常麻烦。更别提有时候在外面，想快速访问家里的服务，还得先连上家里的网络环境，流程繁琐。直到我遇到了Portarium这个项目，它完美地解决了我的问题。

简单来说，Portarium 是一个自托管的、轻量级的服务仪表盘和反向代理工具。你可以把它想象成一个为你所有服务定制的“浏览器主页”或“导航页”，但它远不止于此。它不仅能将你分散在不同服务器、不同端口的服务，通过一个统一的、美观的界面集中展示和管理，还能在后台充当一个智能的“流量分发器”（反向代理），让你通过一个主域名和不同的子路径或子域名，安全、便捷地访问内网服务。对于拥有多个自托管服务（比如Nextcloud、Jellyfin、Bitwarden、各种数据库管理界面、监控面板等）的个人开发者、极客或小团队来说，Portarium 极大地简化了日常运维和访问的复杂度。

它的核心价值在于“统一入口”和“简化管理”。你不用再记忆一堆IP和端口，只需要记住 Portarium 这一个地址。通过它清晰的界面，你可以一键跳转到任何已配置的服务。同时，它的反向代理功能可以帮你处理SSL证书、访问控制等繁琐问题，让你能更安全地从外部网络访问内部服务。接下来，我将详细拆解 Portarium 的设计思路、部署过程、核心功能配置以及我实际使用中积累的经验和踩过的坑。

2. 整体架构与设计思路拆解

2.1 为什么选择 Portarium 而非其他方案？

在自建服务导航和反向代理领域，其实有不少选择，比如 Nginx Proxy Manager、Traefik，或者更简单的 Heimdall、Homer 等静态仪表盘。Portarium 的独特之处在于它巧妙地平衡了功能性和易用性。

Nginx Proxy Manager 和 Traefik 功能强大，是专业的反向代理工具，但它们的配置对于只想快速搭建一个导航页的用户来说，略显复杂，学习曲线较陡。Heimdall 和 Homer 是纯粹的仪表盘，界面漂亮，配置简单，但它们缺乏反向代理能力，意味着你暴露给公网的服务仍然需要单独配置 Nginx 或 Caddy 来处理SSL和路由，增加了维护成本。

Portarium 则采用了“All-in-One”的思路。它内置了 Caddy 作为反向代理引擎，这是一个以自动 HTTPS 闻名的高性能 Web 服务器。这意味着，你只需要在 Portarium 的 Web 界面上点点鼠标，配置好服务地址和域名，Portarium 就会自动调用 Caddy 为你生成反向代理配置，并自动申请和续期 Let‘s Encrypt 的 SSL 证书。对于用户而言，完全无需接触 Caddyfile 或 Nginx 配置文件，体验非常友好。

2.2 Portarium 的核心组件与工作流程

理解 Portarium 的架构，有助于后续的问题排查和高级配置。它主要由以下几个部分组成：

前端界面 (Frontend)：基于现代 Web 技术（如 React/Vue）构建的用户操作界面。这是我们进行服务添加、删除、编辑和查看的主要入口。它通过 RESTful API 与后端通信。
后端 API (Backend)：接收前端请求，处理业务逻辑（如服务的增删改查），并将配置信息持久化到数据库中。
数据库 (Database)：通常使用 SQLite（默认）或 PostgreSQL。用于存储所有配置信息，包括服务列表、代理规则、用户设置等。SQLite 模式使得部署极其简单，开箱即用。
Caddy 服务器 (Reverse Proxy Engine)：这是 Portarium 的“引擎”。后端 API 在修改配置后，会动态生成或更新 Caddy 的配置文件 (Caddyfile)，然后通知 Caddy 重新加载配置。Caddy 负责实际的网络请求转发、TLS 终止等重活。
Docker 集成 (可选但推荐)：Portarium 官方强烈推荐使用 Docker 和 Docker Compose 部署。这不仅简化了安装，更重要的是，Portarium 可以与你 Docker 宿主机的 Docker Daemon 通信，实现“自动发现”功能——自动将宿主上运行的 Docker 容器作为可选服务添加到仪表盘，这是它的一大亮点。

其工作流程可以概括为：用户在 Web 界面添加一个服务（例如，内网的 Jellyfin 服务，地址为http://192.168.1.100:8096，并分配子域名media.yourdomain.com）。后端将此配置存入数据库，并生成对应的 Caddy 配置块。Caddy 加载新配置后，所有发往media.yourdomain.com的 HTTPS 请求都会被 Portarium 所在的服务器接收，然后由 Caddy 透明地转发到内网的192.168.1.100:8096。对于浏览器和 Jellyfin 服务来说，它们感知不到 Portarium/Caddy 的存在，就像直接通信一样。

3. 部署实践与初始配置详解

3.1 环境准备与部署方式选择

Portarium 的部署非常灵活，但为了获得最佳体验（尤其是Docker自动发现功能），我强烈推荐使用Docker Compose方式。

先决条件：

一台运行 Linux 的服务器（VPS 或家庭服务器均可），建议内存 1GB 以上。
服务器上已安装 Docker 和 Docker Compose。
一个属于自己的域名（例如yourdomain.com），并将这个域名的 DNS A 记录指向你的服务器公网 IP。如果你只想在内网使用，可以忽略域名，使用IP访问，但会失去自动HTTPS等便利功能。
确保服务器的80和443端口在防火墙中开放（如果要从公网访问）。

注意：如果你在家庭网络，并且有动态公网IP，你需要配置 DDNS（动态域名解析），将你的域名动态绑定到变化的IP上。很多路由器自带此功能，或者使用ddclient等工具。

3.2 使用 Docker Compose 一键部署

这是最简洁、最不易出错的方式。在你的服务器上创建一个目录，例如portarium，然后创建docker-compose.yml文件。

version: '3.8' services: portarium: image: portainer/portainer-ce:latest # 注意：原项目镜像可能不同，此处以Portainer为例示意，实际需查证 # 实际 Portarium 的镜像可能为 `lscr.io/linuxserver/portainer` 或其他，请以项目官方文档为准。 # 此处假设项目镜像为 `portarium/portarium:latest` container_name: portarium restart: unless-stopped ports: - "9443:9443" # Portarium 管理界面 HTTPS 端口 - "80:80" # 将主机80端口映射给Caddy，用于HTTP挑战和重定向 - "443:443" # 将主机443端口映射给Caddy，用于HTTPS服务 environment: - PUID=1000 - PGID=1000 - TZ=Asia/Shanghai volumes: - ./data:/data # 持久化配置数据 - ./caddy_data:/caddy_data # Caddy 的证书和数据持久化 - /var/run/docker.sock:/var/run/docker.sock:ro # 关键！用于Docker自动发现 networks: - portarium_network networks: portarium_network: driver: bridge

关键配置解析：

镜像 (image)：你需要替换为 Portarium 项目在 Docker Hub 上的官方镜像名。由于输入信息有限，我假设其为portarium/portarium:latest。请务必查阅项目官方文档（如GitHub README）确认正确的镜像名称。一个常见的错误就是使用了错误或已过时的镜像。
端口映射 (ports)：
- 9443:9443: 这是 Portarium 自身管理后台的 HTTPS 端口。你可以通过https://your-server-ip:9443访问。
- 80:80和443:443: 这是最关键的映射。它将宿主机的 80 和 443 端口直接暴露给 Portarium 容器内的 Caddy 服务器。这样，Caddy 才能正常响应来自公网的 HTTP-01 或 TLS-ALPN-01 挑战，从而自动申请 SSL 证书。如果你在宿主机上已经有其他 Web 服务器（如 Nginx）占用了这些端口，必须先停止它们或修改 Portarium 的映射（如8080:80,8443:443），但这会使得自动 HTTPS 变得复杂，不推荐。
卷映射 (volumes)：
- ./data:/data: 持久化 Portarium 的应用数据（数据库、配置等）。即使容器删除，数据也不会丢失。
- ./caddy_data:/caddy_data: 持久化 Caddy 的数据，主要是 SSL 证书。证书申请一次后会被保存，下次启动无需重新申请。
- /var/run/docker.sock:/var/run/docker.sock:ro:这是实现 Docker 自动发现功能的灵魂所在。以只读 (ro) 方式将宿主机的 Docker 守护进程套接字挂载到容器内，使得 Portarium 容器能够与宿主机 Docker 通信，查询正在运行的容器列表。安全提示：这相当于给了 Portarium 容器很高的权限（可以管理宿主机Docker），因此请确保你信任该软件，并且仅在内网或受信任的环境中使用。在生产环境，可能需要更精细的权限控制。
环境变量 (environment)：
- PUID/PGID: 设置容器内进程运行的用户和组ID，通常与你宿主机上想拥有这些数据文件的用户一致。可以用id $USER命令查看。
- TZ: 设置时区，保证日志和时间显示正确。

创建好文件后，在该目录下执行docker-compose up -d，Docker 就会拉取镜像并启动容器。首次启动可能会稍慢，因为 Caddy 要初始化。

3.3 初始访问与基本设置

容器启动后，在浏览器访问https://你的服务器IP:9443。首次访问会提示你创建管理员账户。

设置管理员：输入用户名、密码（务必使用强密码），点击创建。
选择数据存储方式：通常会提示你数据存储在哪里，因为我们做了卷映射，选择本地存储即可。
进入主界面：登录后，你会看到 Portarium 的主仪表盘。初始状态可能是空的。
连接 Docker 环境（可选但推荐）：在侧边栏找到“环境”或“端点”选项。因为我们已经挂载了 Docker Socket，Portarium 通常能自动检测到“本地”Docker 环境并添加。如果没有，可以手动添加，类型选择“Docker”，URL 填写unix:///var/run/docker.sock（这就是我们挂载的路径）。添加成功后，你就能在 Portarium 里看到宿主机上运行的所有容器了，这为后续的自动添加服务提供了便利。

4. 核心功能配置与实战应用

4.1 添加第一个反向代理服务（手动模式）

假设我们内网有一台服务器，上面运行着 Jellyfin 媒体服务器，地址是http://192.168.1.100:8096。我们想通过media.yourdomain.com来安全地访问它。

进入“服务”或“应用”管理页面：在 Portarium 界面中找到添加服务的地方。
创建新服务：
- 服务名称：起个易记的名字，如My-Jellyfin。
- 服务类型：选择HTTP或Web。
- 上游地址 (Upstream)：填写 Jellyfin 的实际内网地址和端口，http://192.168.1.100:8096。确保 Portarium 所在的容器能够通过网络访问到这个地址。如果 Jellyfin 和 Portarium 不在同一台宿主机，需要确保网络互通；如果在同一宿主机但不在同一 Docker 网络，可以使用宿主机的内部IP或 Docker 的内部网络IP。
- 域名/访问路径：这是配置反向代理的关键。填写你想要的外部访问地址，例如media.yourdomain.com。Portarium 会把这个域名交给 Caddy 处理。
- HTTPS/SSL：通常默认开启“自动 HTTPS”。这意味着 Portarium 会指示 Caddy 为media.yourdomain.com自动从 Let‘s Encrypt 申请并配置 SSL 证书。前提是你的80/443端口已正确映射，且域名A记录已指向当前服务器。
- 高级选项：可能包括设置访问控制（基础认证）、添加自定义 HTTP 头、WebSocket 支持等。对于 Jellyfin，可能需要开启 WebSocket 支持以获得更好的体验。
保存并应用：保存配置后，Portarium 后端会生成 Caddy 配置并通知 Caddy 重载。这个过程几乎是瞬间的。
测试访问：现在，你可以在任何能解析media.yourdomain.com到你的服务器公网 IP 的地方，使用浏览器访问https://media.yourdomain.com。你应该能看到 Jellyfin 的登录界面，并且地址栏显示为安全的 HTTPS 连接。

4.2 利用 Docker 自动发现添加服务

这是 Portarium 最省心的功能。如果你的服务（如 Nextcloud, Bitwarden）也是通过 Docker 运行在同一台宿主机上，那么添加它们到仪表盘只需点击几下。

确保 Portarium 已正确连接到本地 Docker 环境（见 3.3 节）。
在“服务”添加页面，选择“从 Docker 容器添加”或类似选项。
系统会列出所有正在运行的容器。找到你的目标容器（例如nextcloud）。
点击它，Portarium 会自动读取该容器的信息，如容器名、镜像名，并尝试自动探测其暴露的端口和可能的访问路径。
你通常只需要补充或确认一下“外部访问域名”（如cloud.yourdomain.com），其他配置（如内部网络地址）Portarium 会自动填充（例如http://nextcloud:80，这里nextcloud是容器名，在 Docker 内部网络中可作为主机名解析）。
保存即可。这样，你就通过容器名而非固定IP来关联服务，即使容器重启后IP变了，连接依然有效，因为 Docker 内部 DNS 会解析到新的IP。

4.3 创建仪表盘与导航页

添加了若干服务后，你就可以创建美观的仪表盘了。

进入“仪表盘”或“主页”编辑界面。
添加小组件：通常有“服务链接”、“状态显示”、“资源监控”等类型的小组件。
配置服务链接：选择“服务链接”小组件，然后从你已添加的服务列表中，选择想要展示在主页的服务。你可以为它们设置自定义图标、背景色和描述。
布局调整：大多数 Portarium 界面支持拖拽布局，你可以自由排列这些服务卡片，形成分类清晰、符合个人习惯的导航页。
设置为主页：将这个自定义仪表盘设置为登录后的默认主页。以后，你只需要登录 Portarium，所有常用服务就一目了然，一键可达。

5. 高级配置与安全加固

5.1 配置访问控制与身份验证

默认情况下，Portarium 的管理界面和它代理的服务都是直接暴露的。为了安全，我们必须加固。

Portarium 管理界面安全：
- 强密码：这是第一道防线。
- 更改默认端口：虽然映射的是9443，但可以考虑在 Docker Compose 中改为一个不常见的端口，减少被端口扫描器发现的风险。
- 设置反向代理前置（推荐）：不要将 Portarium 的管理端口直接暴露在公网。更好的做法是，用 Portarium 本身（或者另一个专门的 Nginx/Caddy 实例）为 Portarium 的管理界面设置一个反向代理，并配置严格的访问控制。
  - 例如，在 Portarium 内添加一个新服务，上游地址指向http://localhost:9443（如果 Portarium 的UI服务在容器内是9443端口），外部域名设为portarium.yourdomain.com。
  - 然后，在这个服务的“高级设置”中，启用“访问控制”或“基础认证”，设置一个用户名和密码。这样，访问https://portarium.yourdomain.com时，需要先输入这个密码才能看到 Portarium 的登录界面，相当于双重认证。
- IP 白名单：如果可能，在防火墙层面设置规则，只允许特定的IP段（如你的家庭IP、公司IP）访问管理端口。
代理服务的访问控制：
- 对于某些不想完全公开的内网服务（如管理后台），可以在 Portarium 添加该服务时，同样启用“基础认证”功能。这样，即使别人知道了你的子域名，没有密码也无法访问。
- 对于更复杂的需求，可以考虑使用 Authelia、Authentik 等开源统一认证系统，与 Portarium/Caddy 集成，实现单点登录和更细粒度的权限控制。

5.2 网络隔离与 Docker 网络规划

将/var/run/docker.sock暴露给容器存在潜在风险。为了最小化攻击面，可以进行网络隔离。

使用独立的 Docker 网络：在docker-compose.yml中，我们创建了portarium_network。确保只有 Portarium 容器在这个网络中。你其他需要被代理的服务容器，可以放在另一个网络（如app_network）中。
跨网络通信：要让 Portarium 能访问到app_network中的服务，有两种方式：
- 将 Portarium 也连接到app_network：在 Portarium 服务的networks部分添加app_network。这样 Portarium 就能直接通过容器名访问该网络中的服务。
- 通过宿主机网络桥接：在添加服务时，上游地址填写宿主机在app_network中的IP（通常是172.x.x.x）或使用host.docker.internal（如果宿主机支持）。这种方式稍复杂。
避免使用host网络模式：除非有特殊需求，否则不要将 Portarium 容器设置为network_mode: host。这虽然能简化一些网络配置，但极大地降低了容器的隔离性。

5.3 备份与恢复策略

你的 Portarium 配置（包括所有服务代理规则）都存储在./data卷中。定期备份这个目录至关重要。

简单备份：定期将./data目录打包压缩，拷贝到其他安全的地方。

# 在 docker-compose.yml 所在目录执行 tar -czf portarium_backup_$(date +%Y%m%d).tar.gz data/

使用脚本自动化备份：可以编写一个简单的 Shell 脚本，结合cron定时任务，每天自动备份并上传到云存储或另一台服务器。
恢复：如果需要迁移或恢复，在新服务器上部署好 Portarium 的 Docker Compose 环境后，先不要启动。将备份的data目录解压覆盖到新环境的./data路径，然后启动容器即可。注意：如果新旧环境的服务器IP或域名结构完全不同，可能需要手动调整数据库（如果懂SQLite）或重新配置部分服务的上游地址。

6. 常见问题排查与实战心得

6.1 证书申请失败 (Let‘s Encrypt ACME Challenge Failed)

这是最常见的问题，表现为访问服务时 HTTPS 证书错误，或在 Portarium 日志中看到 ACME 相关的错误信息。

原因与排查：
1. 端口未正确映射/占用：确保docker-compose.yml中80:80和443:443映射正确，且宿主机这两个端口没有被其他进程（如 Nginx, Apache）占用。使用sudo netstat -tulpn | grep :80和sudo netstat -tulpn | grep :443检查。
2. 防火墙/安全组未开放：检查云服务商的安全组规则和服务器本身的防火墙（如ufw），确保入站方向的80/TCP和443/TCP是开放的。
3. 域名解析未生效或错误：使用ping yourdomain.com和dig media.yourdomain.com检查域名是否已正确解析到你的服务器公网 IP。注意 DNS 记录生效可能有延迟（TTL）。
4. 速率限制：Let‘s Encrypt 对同一域名有申请频率限制（每周最多50张证书）。如果你在短时间内多次尝试和失败，可能会被限流。等待一段时间再试。
解决方案：
- 针对1、2、3点，修正端口映射、关闭占用进程、配置防火墙、等待DNS生效。
- 如果急需使用，可以在 Portarium 中暂时为该服务关闭“自动 HTTPS”，或者使用自签名证书过渡。但长期务必解决上述问题以启用自动 HTTPS。
- 查看 Portarium 容器和 Caddy 的日志，获取更详细的错误信息：docker logs portarium。

6.2 服务能添加但无法访问 (502 Bad Gateway / Connection Refused)

在 Portarium 中添加了服务，但通过配置的域名访问时，出现 502 错误或连接被拒绝。

原因与排查：
1. 上游服务不可达：Portarium/Caddy 无法连接到你填写的上游地址（如http://192.168.1.100:8096）。
  - 检查上游服务是否正在运行。
  - 检查网络连通性：在 Portarium 容器内执行docker exec -it portarium curl http://192.168.1.100:8096，看是否能访问到目标服务。如果失败，说明网络不通。
2. Docker 网络问题：如果使用容器名（如http://jellyfin:8096）作为上游地址，确保 Portarium 容器和目标服务容器在同一个 Docker 网络中，或者网络是互通的。
3. 上游服务绑定地址：确保上游服务（如 Jellyfin）监听的是0.0.0.0而非127.0.0.1。如果服务只绑定在127.0.0.1，那么只有本机可以访问，容器无法访问。
解决方案：
- 对于1和3，确保服务运行并监听在所有接口上。
- 对于2，调整 Docker 网络配置，将相关容器加入同一网络。在docker-compose.yml中为服务定义共用网络是最清晰的方式。

6.3 Docker 自动发现功能不工作

在 Portarium 界面中看不到宿主机上的容器列表。

原因与排查：
1. Docker Socket 挂载错误：检查docker-compose.yml中 volumes 部分，路径是否正确（/var/run/docker.sock），权限是否为:ro。
2. SELinux/AppArmor 限制（某些 Linux 发行版）：安全模块可能阻止容器访问宿主机的 Docker Socket。可以尝试临时禁用 SELinux (setenforce 0) 测试，或添加相应的安全策略。
3. Portarium 容器权限不足：虽然挂载了 Socket，但容器内的用户可能没有读取它的权限。确保环境变量PUID/PGID设置的用户有权限访问/var/run/docker.sock（通常属于docker组）。
解决方案：
- 确认挂载路径无误。
- 在宿主机上，将用于运行容器的用户（PUID对应的用户）加入docker组：sudo usermod -aG docker $USER，然后重新登录生效。
- 对于 SELinux，可以尝试在docker-compose.yml的 volumes 部分添加:z或:Z后缀（如/var/run/docker.sock:/var/run/docker.sock:ro,z）来重新标记卷，但这需要根据你的系统谨慎操作。

6.4 性能与资源占用

Portarium 本身非常轻量，资源消耗主要来自 Caddy 和其代理的后端服务。Caddy 以高性能和低内存占用著称。在我的树莓派 4B (4GB内存) 上，运行 Portarium 并代理约10个服务，内存占用长期在 150MB 左右，CPU 使用率几乎可忽略不计，完全能满足家庭和小型办公场景的需求。

个人使用心得：

起步阶段：先用手动模式添加一两个核心服务，熟悉流程。确保基础的反向代理和 HTTPS 工作正常。
善用标签：在添加服务时，可以使用标签（Tags）对服务进行分类，如media,tools,monitoring。这样在创建仪表盘时，可以按标签筛选，让主页更整洁。
定期检查日志：Portarium 和 Caddy 的日志是排查问题的金钥匙。养成定期查看日志的习惯，可以及时发现配置错误或异常访问。
组合使用：Portarium 非常适合作为对外暴露服务的统一网关和导航页。对于纯粹内部、无需从公网访问的服务，可以考虑使用更简单的工具（如 Heimdall）做导航，以进一步减少潜在攻击面。
保持更新：关注 Portarium 项目的更新，定期更新镜像可以获得新功能和安全性修复。更新前，务必备份好data目录。