feat: add Centrifugo

Package the official latest and v6.9.1 images with authenticated HTTP/WebSocket defaults and 1Panel lifecycle scripts.
2026-10-02 00:00:15 +00:00 · 2026-07-31 01:42:10 +08:00
parent 59ef536922
commit ae55382867
15 changed files with 577 additions and 0 deletions
@@ -0,0 +1,10 @@
+CONTAINER_NAME=centrifugo
+PANEL_APP_PORT_HTTP=8000
+CENTRIFUGO_CLIENT_ALLOWED_ORIGINS=
+CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY=replace-with-a-random-hmac-secret
+CENTRIFUGO_HTTP_API_KEY=replace-with-a-random-api-key
+CENTRIFUGO_ADMIN_ENABLED=true
+CENTRIFUGO_ADMIN_PASSWORD=replace-with-a-strong-admin-password
+CENTRIFUGO_ADMIN_SECRET=replace-with-a-random-session-secret
+CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT=true
+CENTRIFUGO_LOG_LEVEL=info
@@ -0,0 +1,176 @@
+additionalProperties:
+  formFields:
+    - default: 8000
+      edit: true
+      envKey: PANEL_APP_PORT_HTTP
+      labelEn: HTTP Port
+      labelZh: HTTP 端口
+      label:
+        en: HTTP Port
+        zh: HTTP 端口
+        zh-Hant: HTTP 連接埠
+        ja: HTTP ポート
+        ko: HTTP 포트
+        ru: Порт HTTP
+        ms: Port HTTP
+        pt-br: Porta HTTP
+      required: true
+      rule: paramPort
+      type: number
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_CLIENT_ALLOWED_ORIGINS
+      labelEn: Allowed Browser Origins
+      labelZh: 允许的浏览器来源
+      label:
+        en: Allowed Browser Origins
+        zh: 允许的浏览器来源
+        zh-Hant: 允許的瀏覽器來源
+        ja: 許可するブラウザーオリジン
+        ko: 허용된 브라우저 출처
+        ru: Разрешенные источники браузера
+        ms: Asal Pelayar Dibenarkan
+        pt-br: Origens de Navegador Permitidas
+      required: false
+      type: text
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY
+      labelEn: Connection Token HMAC Secret
+      labelZh: 连接令牌 HMAC 密钥
+      label:
+        en: Connection Token HMAC Secret
+        zh: 连接令牌 HMAC 密钥
+        zh-Hant: 連線權杖 HMAC 密鑰
+        ja: 接続トークン HMAC シークレット
+        ko: 연결 토큰 HMAC 비밀 키
+        ru: Секрет HMAC токена подключения
+        ms: Rahsia HMAC Token Sambungan
+        pt-br: Segredo HMAC do Token de Conexão
+      random: true
+      required: true
+      type: password
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_HTTP_API_KEY
+      labelEn: HTTP API Key
+      labelZh: HTTP API 密钥
+      label:
+        en: HTTP API Key
+        zh: HTTP API 密钥
+        zh-Hant: HTTP API 密鑰
+        ja: HTTP API キー
+        ko: HTTP API 키
+        ru: Ключ HTTP API
+        ms: Kunci API HTTP
+        pt-br: Chave da API HTTP
+      random: true
+      required: true
+      type: password
+    - default: "true"
+      edit: true
+      envKey: CENTRIFUGO_ADMIN_ENABLED
+      labelEn: Enable Admin UI
+      labelZh: 启用管理界面
+      label:
+        en: Enable Admin UI
+        zh: 启用管理界面
+        zh-Hant: 啟用管理介面
+        ja: 管理画面を有効化
+        ko: 관리 화면 활성화
+        ru: Включить панель администратора
+        ms: Dayakan Antara Muka Pentadbir
+        pt-br: Ativar Interface Administrativa
+      required: true
+      type: select
+      values:
+        - label: "true"
+          value: "true"
+        - label: "false"
+          value: "false"
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_ADMIN_PASSWORD
+      labelEn: Admin Password
+      labelZh: 管理密码
+      label:
+        en: Admin Password
+        zh: 管理密码
+        zh-Hant: 管理密碼
+        ja: 管理者パスワード
+        ko: 관리자 비밀번호
+        ru: Пароль администратора
+        ms: Kata Laluan Pentadbir
+        pt-br: Senha do Administrador
+      random: true
+      required: true
+      type: password
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_ADMIN_SECRET
+      labelEn: Admin Session Secret
+      labelZh: 管理会话密钥
+      label:
+        en: Admin Session Secret
+        zh: 管理会话密钥
+        zh-Hant: 管理工作階段密鑰
+        ja: 管理セッションシークレット
+        ko: 관리자 세션 비밀 키
+        ru: Секрет сеанса администратора
+        ms: Rahsia Sesi Pentadbir
+        pt-br: Segredo da Sessão Administrativa
+      random: true
+      required: true
+      type: password
+    - default: "true"
+      edit: true
+      envKey: CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT
+      labelEn: Allow Client Subscriptions
+      labelZh: 允许客户端订阅
+      label:
+        en: Allow Client Subscriptions
+        zh: 允许客户端订阅
+        zh-Hant: 允許用戶端訂閱
+        ja: クライアント購読を許可
+        ko: 클라이언트 구독 허용
+        ru: Разрешить подписки клиентов
+        ms: Benarkan Langganan Klien
+        pt-br: Permitir Assinaturas de Clientes
+      required: true
+      type: select
+      values:
+        - label: "true"
+          value: "true"
+        - label: "false"
+          value: "false"
+    - default: info
+      edit: true
+      envKey: CENTRIFUGO_LOG_LEVEL
+      labelEn: Log Level
+      labelZh: 日志级别
+      label:
+        en: Log Level
+        zh: 日志级别
+        zh-Hant: 日誌等級
+        ja: ログレベル
+        ko: 로그 수준
+        ru: Уровень журналирования
+        ms: Tahap Log
+        pt-br: Nível de Log
+      required: true
+      type: select
+      values:
+        - label: trace
+          value: trace
+        - label: debug
+          value: debug
+        - label: info
+          value: info
+        - label: warn
+          value: warn
+        - label: error
+          value: error
+        - label: fatal
+          value: fatal
+        - label: none
+          value: none
@@ -0,0 +1,31 @@
+services:
+  centrifugo:
+    image: "centrifugo/centrifugo:v6.9.1"
+    container_name: ${CONTAINER_NAME}
+    restart: unless-stopped
+    networks:
+      - 1panel-network
+    ports:
+      - "${PANEL_APP_PORT_HTTP}:8000"
+    environment:
+      - CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY=${CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY}
+      - CENTRIFUGO_CLIENT_ALLOWED_ORIGINS=${CENTRIFUGO_CLIENT_ALLOWED_ORIGINS}
+      - CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT=${CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT}
+      - CENTRIFUGO_HTTP_API_KEY=${CENTRIFUGO_HTTP_API_KEY}
+      - CENTRIFUGO_ADMIN_ENABLED=${CENTRIFUGO_ADMIN_ENABLED}
+      - CENTRIFUGO_ADMIN_PASSWORD=${CENTRIFUGO_ADMIN_PASSWORD}
+      - CENTRIFUGO_ADMIN_SECRET=${CENTRIFUGO_ADMIN_SECRET}
+      - CENTRIFUGO_HEALTH_ENABLED=true
+      - CENTRIFUGO_LOG_LEVEL=${CENTRIFUGO_LOG_LEVEL}
+    healthcheck:
+      test: ["CMD-SHELL", "wget --spider -q http://127.0.0.1:8000/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      start_period: 10s
+      retries: 10
+    labels:
+      createdBy: "Apps"
+
+networks:
+  1panel-network:
+    external: true
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exit 0
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v docker-compose >/dev/null 2>&1; then
+  docker-compose down --volumes --remove-orphans
+else
+  docker compose down --volumes --remove-orphans
+fi
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exit 0
@@ -0,0 +1,83 @@
+# Centrifugo
+
+## 产品介绍
+
+Centrifugo 是一个面向应用的实时消息服务器。应用后端通过 HTTP API 发布消息，已认证的客户端通过 WebSocket 等传输订阅频道并实时接收消息。
+
+本应用使用 Centrifugo 官方镜像和默认内存引擎，以单个非 root 容器运行，不依赖数据库或缓存服务。
+
+## 主要功能
+
+- 通过默认启用的 WebSocket 端点向在线客户端实时传送消息
+- 使用 JWT 验证客户端连接，并通过 HTTP API 密钥保护后端发布接口
+- 在内置管理界面中查看节点、连接和频道，并执行受控发布操作
+- 使用健康检查监控单节点服务状态
+
+## 访问说明
+
+- 管理界面：`http://<主机>:<安装端口>/`
+- WebSocket：`ws://<主机>:<安装端口>/connection/websocket`
+- HTTP 发布 API：`POST http://<主机>:<安装端口>/api/publish`
+
+反向代理 WebSocket 时需要保留 Upgrade/Connection 请求头。公网部署还应在防火墙、安全组和反向代理中限制管理入口与 API 访问。
+
+## 默认安全配置
+
+- 连接必须使用由 `CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY` 签名的 JWT。
+- HTTP 发布 API 必须提供 `CENTRIFUGO_HTTP_API_KEY`。
+- 管理界面默认启用，并使用随机管理密码和随机会话密钥保护。
+- 默认允许已认证客户端订阅无命名空间频道，便于完成官方快速入门流程。生产环境可在安装表单中关闭该选项并改用上游的命名空间或代理授权策略。
+- 浏览器应用应在 `CENTRIFUGO_CLIENT_ALLOWED_ORIGINS` 中填写允许的源，多个源使用空格分隔。非浏览器客户端未发送 `Origin` 时不受该配置影响。
+
+所有密钥均由 1Panel 在安装时随机生成。请妥善保存安装参数，不要把 JWT 签名密钥、HTTP API 密钥或管理会话密钥发送给客户端。
+
+## 使用说明
+
+安装后通过表单设置的 HTTP 端口打开管理界面。使用管理密码登录后，可以查看节点和连接，并通过 Actions 页面向频道发布消息。
+
+客户端 WebSocket 地址为：
+
+```text
+ws://<主机>:<端口>/connection/websocket
+```
+
+可以在 1Panel 的容器终端中使用官方 CLI 为测试用户生成连接令牌：
+
+```bash
+centrifugo gentoken -u demo-user
+```
+
+应用后端通过 `POST /api/publish` 发布消息，并在 `X-API-Key` 请求头中提供安装时生成的 HTTP API 密钥。详细的客户端订阅与发布示例请参阅上游快速入门文档。
+
+## 数据与重启
+
+默认内存引擎不保存消息历史、在线状态或频道状态，因此本应用没有持久卷。容器重启会断开现有客户端并清空内存状态；客户端应重新连接和订阅。安装配置与随机密钥由 1Panel 的应用环境保留，重启后认证配置保持不变。
+
+需要 Redis、NATS、PostgreSQL、Kafka 或其他扩展拓扑时，请按照上游文档单独规划依赖、扩缩容、持久化和升级流程；这些模式不属于本默认单机包。
+
+## 安全说明
+
+交付时镜像包含 `grpc-go` 的 High 级公告 `GHSA-hrxh-6v49-42gf`。该公告影响 gRPC/xDS RBAC 与 gRPC HTTP/2 服务端；本包不启用或暴露 Centrifugo 的 gRPC API 和单向 gRPC 端点，因此默认拓扑不会进入对应代码路径。启用上游 gRPC 功能前应升级到包含修复依赖的镜像并重新评估风险。
+
+## 参考资料
+
+- 官网：<https://centrifugal.dev/>
+- 快速入门：<https://centrifugal.dev/docs/getting-started/quickstart>
+- 配置说明：<https://centrifugal.dev/docs/server/configuration>
+- 源码：<https://github.com/centrifugal/centrifugo>
+- 官方镜像：<https://hub.docker.com/r/centrifugo/centrifugo>
+
+## Introduction
+
+Centrifugo is a real-time messaging server for applications. Backends publish through the authenticated HTTP API, while authenticated clients subscribe over WebSocket and other supported transports.
+
+This package runs the official image as one non-root service with the default in-memory engine. It enables the authenticated admin UI, connection JWT verification, HTTP API key authorization, health checks, and client-side channel subscriptions. It does not enable or expose gRPC endpoints.
+
+## Features
+
+- Authenticated real-time messaging through the default WebSocket endpoint
+- API-key-protected backend publishing over HTTP
+- Built-in authenticated administration UI for nodes, connections, channels, and publish actions
+- Container health monitoring through the upstream `/health` endpoint
+
+The default engine has no persistent state. Existing clients disconnect and in-memory channel state is cleared when the container restarts, while 1Panel retains the install configuration and generated secrets. See the upstream documentation before adopting Redis, NATS, PostgreSQL, Kafka, or a clustered topology.
@@ -0,0 +1,32 @@
+name: Centrifugo
+tags:
+  - DevOps
+title: 面向应用的实时消息与发布订阅服务器
+description: 面向应用的实时消息与发布订阅服务器
+additionalProperties:
+  key: centrifugo
+  name: Centrifugo
+  tags:
+    - DevOps
+  shortDescZh: 面向应用的实时消息与发布订阅服务器
+  shortDescEn: Real-time messaging and publish-subscribe server for applications
+  description:
+    en: Real-time messaging and publish-subscribe server for applications
+    zh: 面向应用的实时消息与发布订阅服务器
+    zh-Hant: 面向應用程式的即時訊息與發佈訂閱伺服器
+    ja: アプリケーション向けのリアルタイムメッセージングと発行・購読サーバー
+    ko: 애플리케이션용 실시간 메시징 및 발행-구독 서버
+    ru: Сервер обмена сообщениями в реальном времени и публикации-подписки для приложений
+    ms: Pelayan pemesejan masa nyata dan terbit-langgan untuk aplikasi
+    pt-br: Servidor de mensagens em tempo real e publicação-assinatura para aplicativos
+  type: tool
+  crossVersionUpdate: true
+  limit: 0
+  recommend: 0
+  memoryRequired: 128
+  website: https://centrifugal.dev/
+  github: https://github.com/centrifugal/centrifugo
+  document: https://centrifugal.dev/docs/getting-started/introduction
+  architectures:
+    - amd64
+    - arm64
@@ -0,0 +1,10 @@
+CONTAINER_NAME=centrifugo
+PANEL_APP_PORT_HTTP=8000
+CENTRIFUGO_CLIENT_ALLOWED_ORIGINS=
+CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY=replace-with-a-random-hmac-secret
+CENTRIFUGO_HTTP_API_KEY=replace-with-a-random-api-key
+CENTRIFUGO_ADMIN_ENABLED=true
+CENTRIFUGO_ADMIN_PASSWORD=replace-with-a-strong-admin-password
+CENTRIFUGO_ADMIN_SECRET=replace-with-a-random-session-secret
+CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT=true
+CENTRIFUGO_LOG_LEVEL=info
@@ -0,0 +1,176 @@
+additionalProperties:
+  formFields:
+    - default: 8000
+      edit: true
+      envKey: PANEL_APP_PORT_HTTP
+      labelEn: HTTP Port
+      labelZh: HTTP 端口
+      label:
+        en: HTTP Port
+        zh: HTTP 端口
+        zh-Hant: HTTP 連接埠
+        ja: HTTP ポート
+        ko: HTTP 포트
+        ru: Порт HTTP
+        ms: Port HTTP
+        pt-br: Porta HTTP
+      required: true
+      rule: paramPort
+      type: number
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_CLIENT_ALLOWED_ORIGINS
+      labelEn: Allowed Browser Origins
+      labelZh: 允许的浏览器来源
+      label:
+        en: Allowed Browser Origins
+        zh: 允许的浏览器来源
+        zh-Hant: 允許的瀏覽器來源
+        ja: 許可するブラウザーオリジン
+        ko: 허용된 브라우저 출처
+        ru: Разрешенные источники браузера
+        ms: Asal Pelayar Dibenarkan
+        pt-br: Origens de Navegador Permitidas
+      required: false
+      type: text
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY
+      labelEn: Connection Token HMAC Secret
+      labelZh: 连接令牌 HMAC 密钥
+      label:
+        en: Connection Token HMAC Secret
+        zh: 连接令牌 HMAC 密钥
+        zh-Hant: 連線權杖 HMAC 密鑰
+        ja: 接続トークン HMAC シークレット
+        ko: 연결 토큰 HMAC 비밀 키
+        ru: Секрет HMAC токена подключения
+        ms: Rahsia HMAC Token Sambungan
+        pt-br: Segredo HMAC do Token de Conexão
+      random: true
+      required: true
+      type: password
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_HTTP_API_KEY
+      labelEn: HTTP API Key
+      labelZh: HTTP API 密钥
+      label:
+        en: HTTP API Key
+        zh: HTTP API 密钥
+        zh-Hant: HTTP API 密鑰
+        ja: HTTP API キー
+        ko: HTTP API 키
+        ru: Ключ HTTP API
+        ms: Kunci API HTTP
+        pt-br: Chave da API HTTP
+      random: true
+      required: true
+      type: password
+    - default: "true"
+      edit: true
+      envKey: CENTRIFUGO_ADMIN_ENABLED
+      labelEn: Enable Admin UI
+      labelZh: 启用管理界面
+      label:
+        en: Enable Admin UI
+        zh: 启用管理界面
+        zh-Hant: 啟用管理介面
+        ja: 管理画面を有効化
+        ko: 관리 화면 활성화
+        ru: Включить панель администратора
+        ms: Dayakan Antara Muka Pentadbir
+        pt-br: Ativar Interface Administrativa
+      required: true
+      type: select
+      values:
+        - label: "true"
+          value: "true"
+        - label: "false"
+          value: "false"
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_ADMIN_PASSWORD
+      labelEn: Admin Password
+      labelZh: 管理密码
+      label:
+        en: Admin Password
+        zh: 管理密码
+        zh-Hant: 管理密碼
+        ja: 管理者パスワード
+        ko: 관리자 비밀번호
+        ru: Пароль администратора
+        ms: Kata Laluan Pentadbir
+        pt-br: Senha do Administrador
+      random: true
+      required: true
+      type: password
+    - default: ""
+      edit: true
+      envKey: CENTRIFUGO_ADMIN_SECRET
+      labelEn: Admin Session Secret
+      labelZh: 管理会话密钥
+      label:
+        en: Admin Session Secret
+        zh: 管理会话密钥
+        zh-Hant: 管理工作階段密鑰
+        ja: 管理セッションシークレット
+        ko: 관리자 세션 비밀 키
+        ru: Секрет сеанса администратора
+        ms: Rahsia Sesi Pentadbir
+        pt-br: Segredo da Sessão Administrativa
+      random: true
+      required: true
+      type: password
+    - default: "true"
+      edit: true
+      envKey: CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT
+      labelEn: Allow Client Subscriptions
+      labelZh: 允许客户端订阅
+      label:
+        en: Allow Client Subscriptions
+        zh: 允许客户端订阅
+        zh-Hant: 允許用戶端訂閱
+        ja: クライアント購読を許可
+        ko: 클라이언트 구독 허용
+        ru: Разрешить подписки клиентов
+        ms: Benarkan Langganan Klien
+        pt-br: Permitir Assinaturas de Clientes
+      required: true
+      type: select
+      values:
+        - label: "true"
+          value: "true"
+        - label: "false"
+          value: "false"
+    - default: info
+      edit: true
+      envKey: CENTRIFUGO_LOG_LEVEL
+      labelEn: Log Level
+      labelZh: 日志级别
+      label:
+        en: Log Level
+        zh: 日志级别
+        zh-Hant: 日誌等級
+        ja: ログレベル
+        ko: 로그 수준
+        ru: Уровень журналирования
+        ms: Tahap Log
+        pt-br: Nível de Log
+      required: true
+      type: select
+      values:
+        - label: trace
+          value: trace
+        - label: debug
+          value: debug
+        - label: info
+          value: info
+        - label: warn
+          value: warn
+        - label: error
+          value: error
+        - label: fatal
+          value: fatal
+        - label: none
+          value: none
@@ -0,0 +1,31 @@
+services:
+  centrifugo:
+    image: "centrifugo/centrifugo:latest"
+    container_name: ${CONTAINER_NAME}
+    restart: unless-stopped
+    networks:
+      - 1panel-network
+    ports:
+      - "${PANEL_APP_PORT_HTTP}:8000"
+    environment:
+      - CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY=${CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY}
+      - CENTRIFUGO_CLIENT_ALLOWED_ORIGINS=${CENTRIFUGO_CLIENT_ALLOWED_ORIGINS}
+      - CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT=${CENTRIFUGO_CHANNEL_WITHOUT_NAMESPACE_ALLOW_SUBSCRIBE_FOR_CLIENT}
+      - CENTRIFUGO_HTTP_API_KEY=${CENTRIFUGO_HTTP_API_KEY}
+      - CENTRIFUGO_ADMIN_ENABLED=${CENTRIFUGO_ADMIN_ENABLED}
+      - CENTRIFUGO_ADMIN_PASSWORD=${CENTRIFUGO_ADMIN_PASSWORD}
+      - CENTRIFUGO_ADMIN_SECRET=${CENTRIFUGO_ADMIN_SECRET}
+      - CENTRIFUGO_HEALTH_ENABLED=true
+      - CENTRIFUGO_LOG_LEVEL=${CENTRIFUGO_LOG_LEVEL}
+    healthcheck:
+      test: ["CMD-SHELL", "wget --spider -q http://127.0.0.1:8000/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      start_period: 10s
+      retries: 10
+    labels:
+      createdBy: "Apps"
+
+networks:
+  1panel-network:
+    external: true
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exit 0
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v docker-compose >/dev/null 2>&1; then
+  docker-compose down --volumes --remove-orphans
+else
+  docker compose down --volumes --remove-orphans
+fi
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exit 0