安装
安装（Installation）
目录
Wavelog Worker 以 Docker 镜像形式分发。这是推荐的运行方式——无需构建工具链。
对于没有 Docker 的环境，也提供预编译的二进制文件以及从源码构建的说明。
Docker（推荐）
该镜像发布在 GitHub Container Registry 上，支持 amd64、arm64 和 arm/v7（Raspberry Pi）。
1. 创建配置文件
在你选定的目录中基于 config.sample.yaml 创建 config.yaml，例如 /opt/wavelog-worker/config.yaml：
ws_port: 9000 # browsers connect here
internal_port: 9001 # Wavelog PHP calls this port
# 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"
worker_secret: "your-secret-here-minimum-32-characters"
用以下命令生成一个强密钥：
openssl rand -hex 32
全部可用选项见配置。
2. 运行容器
docker run -d \
--name wavelog-worker \
--restart unless-stopped \
-p 9000:9000 \
-p 9001:9001 \
-v /opt/wavelog-worker/config.yaml:/app/config.yaml:ro \
ghcr.io/wavelog/wavelog_worker:latest
警告：内部端口
端口 9001（内部 API）只需要对 Wavelog 的 PHP 服务器可达。 如果两个服务运行在同一主机或同一 Docker 网络上，你可以省略
-p 9001:9001而改用 Docker 网络。
3. 验证运行状态
curl -s -H "X-Worker-Secret: your-secret-here-minimum-32-characters" \
http://localhost:9001/internal/status | python3 -m json.tool
正常响应如下所示：
{
"status": "ok",
"version": "0.3.0",
"uptime": "2m30s",
"registered_topics": 0,
"active_topics": 0,
"connected_clients": 0,
"connected_sockets": 0,
"cluster_nodes": -1,
"nodes": [ { "name": "myhost", "alive": true, "...": "..." } ]
}
cluster_nodes: -1 表示单实例模式（未使用 Redis）。这是预期情况。此时 nodes 中只包含这一个 worker。
Docker Compose
如果你用 Docker Compose 运行 Wavelog，请把 Worker 作为服务加入同一个栈：
services:
wavelog:
image: ghcr.io/wavelog/wavelog:latest
# ... your existing Wavelog config ...
wavelog-worker:
image: ghcr.io/wavelog/wavelog_worker:latest
restart: unless-stopped
ports:
- "9000:9000" # exposed to browsers
# 9001 stays internal — Wavelog reaches it via Docker network
volumes:
- ./worker/config.yaml:/app/config.yaml:ro
在这种配置下，Wavelog 的 PHP 可以通过 http://wavelog-worker:9001 访问 Worker——请在 Wavelog 配置中把它作为内部 URL 使用。
提示：无需配置文件
除了挂载
config.yaml，你也可以把所有内容作为环境变量传入：
yaml wavelog-worker: image: ghcr.io/wavelog/wavelog_worker:latest restart: unless-stopped ports: - "9000:9000" environment: WORKER_INTERNAL_BIND: "0.0.0.0" WORKER_SECRET: "${WORKER_SECRET}"完整列表见配置 → 环境变量。
反向代理（HTTPS / WSS）
通过 HTTPS 连接的浏览器必须使用安全 WebSocket（wss://）。请配置反向代理，把 WebSocket 连接转发到端口 9000。
Nginx
location /worker/ {
proxy_pass http://127.0.0.1:9000/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
}
Apache
ProxyPass /worker/ ws://127.0.0.1:9000/
ProxyPassReverse /worker/ ws://127.0.0.1:9000/
RewriteEngine on
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule /worker/(.*) ws://127.0.0.1:9000/$1 [P,L]
二进制文件（不使用 Docker）
每个 GitHub 发行版都附带预编译好的二进制文件。
下载适用于你的平台的二进制文件，把 config.yaml 放在它旁边，然后运行：
wavelog_worker --config config.yaml
从源码构建
需要 Go 1.24 或更高版本。
git clone https://github.com/wavelog/wavelog_worker.git
cd wavelog_worker
make
./dist/wavelog_worker --config config.yaml
systemd 服务
创建 /etc/systemd/system/wavelog-worker.service：
[Unit]
Description=Wavelog Worker
After=network.target
[Service]
User=wavelog-worker
WorkingDirectory=/opt/wavelog_worker
ExecStart=/opt/wavelog_worker/dist/wavelog_worker --config /opt/wavelog_worker/config.yaml
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
启用并启动：
systemctl daemon-reload
systemctl enable --now wavelog-worker
下一步
继续阅读 Wavelog 集成，把你的 Wavelog 实例指向正在运行的 Worker。