配置参考

配置参考（Configuration Reference）

目录

• 完整示例
• 选项参考
  • ws_port
  • internal_port
  • ws_bind
  • internal_bind
  • worker_secret
  • redis_url
• 环境变量
• 默认值汇总
• 端口概览

Worker 通过单个 YAML 文件配置，该文件由 --config 参数传入（默认：工作目录下的 config.yaml），也可通过 WORKER_* 环境变量配置（见环境变量）。两者可以结合使用：环境变量覆盖文件中的值，而文件可以完全不存在。

完整示例

# config.yaml

ws_port: 9000        # WebSocket port — browsers connect here
internal_port: 9001  # Internal API port — Wavelog PHP connects here

# Optional: bind addresses. Empty/omitted = listen on all interfaces (0.0.0.0 + ::).
# Tip: restrict the internal API (carries worker_secret) to localhost.
# ws_bind: "0.0.0.0"
# internal_bind: "127.0.0.1"

# Shared secret — must match the value in Wavelog's worker.php config.
# Minimum 32 characters. Generate with: openssl rand -hex 32
worker_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Optional: Redis URL for multi-instance clustering.
# Omit or leave empty for single-instance mode.
# redis_url: "redis://localhost:6379/2"

---

选项参考

ws_port

类型	整数
默认值	9000
是否必填	否

Worker 在此 TCP 端口上监听来自浏览器的入站 WebSocket 连接。

浏览器连接到 ws://your-host:9000/ws?topic=<topic>。使用反向代理提供 HTTPS 时，此端口无需对外暴露。

---

internal_port

类型	整数
默认值	9001
是否必填	否

内部 HTTP API 所用的 TCP 端口。Wavelog 的 PHP 后端使用此端口来：

• 注册和注销主题
• 向已连接的客户端发布广播事件
• 查询 Worker 的状态

此端口不应暴露到互联网。请将其限制在内网或 Docker 网络内。

---

ws_bind

类型	字符串
默认值	0.0.0.0
是否必填	否

WebSocket 服务所绑定的 IP 地址。这就是反向代理需要能从外部访问到的 IP。

---

internal_bind

类型	字符串
默认值	127.0.0.1
是否必填	否

与 Wavelog 内部通信所用的 IP 地址。此端口只需 Wavelog 本身可达。如果 Wavelog Worker 运行在同一台主机上，该 IP 应设为 127.0.0.1。否则请确保配置了合适的防火墙。

---

worker_secret

类型	字符串
默认值	—
是否必填	是
最小长度	32 个字符

一个共享密钥，用于认证 Wavelog 的 PHP 后端与 Worker 之间的所有通信。每个发往内部 API 的请求都必须在 X-Worker-Secret HTTP 请求头中携带该值。

同样的密钥必须在 Wavelog 侧配置于 application/config/worker.php 中。

生成密钥：

openssl rand -hex 32

警告：保守密钥

请像对待密码一样对待 worker_secret。任何知道它的人都能向所有已连接的客户端推送任意消息。切勿将其暴露在日志或版本控制中。

---

redis_url

类型	字符串
默认值	（空——单实例模式）
是否必填	否

一个 Redis 连接 URL。设置后，Worker 使用 Redis 发布/订阅在多个 Worker 实例之间同步广播事件，并在 Redis 中注册自身，因此 Wavelog 只需要一个 Worker URL。Wavelog 中显示的节点名即主机名（在 Docker Compose 中设置 hostname:；在 Kubernetes 中为 Pod 名称）。

redis_url: "redis://localhost:6379/2"

URL 格式遵循标准 Redis URL 方案：

redis://[:password@]host[:port][/db]
rediss://...   # TLS

请使用专用的 Redis 数据库（例如 /2），以避免与其他应用发生键冲突。

当 redis_url 为空或省略时，Worker 以单实例模式运行：所有状态都在内存中，重启后丢失。Wavelog 会在下次页面加载时自动重新注册主题。

关于何时以及如何使用 Redis，见集群。

---

环境变量

每个选项都可以通过环境变量设置。这是 Docker 和 Kubernetes 中的自然方式：无需挂载配置文件，密钥来自 Docker/Kubernetes 的 secret。

变量	配置选项
WORKER_WS_BIND	ws_bind
WORKER_WS_PORT	ws_port
WORKER_INTERNAL_BIND	internal_bind
WORKER_INTERNAL_PORT	internal_port
WORKER_SECRET	worker_secret
WORKER_REDIS_URL	redis_url
WORKER_TOPIC_TTL	topic_ttl

规则：

• 已设置且非空的变量会覆盖 config.yaml 中的值。空变量被忽略。
• 如果配置文件不存在，Worker 会以默认值加环境变量启动。日志会显示 config: config.yaml not found, using WORKER_* environment variables only。文件的任何其他问题（不可读、YAML 无效）仍然算作错误。
• worker_secret / WORKER_SECRET 无论来自哪个来源，都至少需要 32 个字符。

不带配置文件的 Docker Compose 示例：

wavelog-worker:
  image: ghcr.io/wavelog/wavelog_worker:latest
  environment:
    WORKER_INTERNAL_BIND: "0.0.0.0"
    WORKER_SECRET: "${WORKER_SECRET}"          # from .env or a secret
    WORKER_REDIS_URL: "redis://wavelog-cache:6379/2"

---

默认值汇总

选项	默认值
ws_port	9000
internal_port	9001
worker_secret	（无——必填）
redis_url	（空——单实例）

---

端口概览

┌──────────────────────────────────────────┐
│              Wavelog Worker              │
│                                          │
│  :9000  WebSocket ──► browsers           │
│  :9001  Internal API ──► Wavelog PHP     │
└──────────────────────────────────────────┘

端口	方向	连接方
9000（WS）	入站	浏览器，经反向代理
9001（内部）	入站	仅 Wavelog PHP