私有部署 (Self-Hosting)

私有部署 PushGo 网关让你可以完全控制自己的数据和通知。该网关是一个使用 Rust 编写的高性能二进制程序。

部署方式

方式一：使用 Docker 部署 (推荐)

推荐使用官方 Docker 镜像进行部署，这是最简单且易于管理的方式。

docker run -d --name pushgo-gateway \
  -p 6666:6666 \
  -p 5223:5223/tcp \
  -p 5223:5223/udp \
  -e PUSHGO_HTTP_ADDR=0.0.0.0:6666 \
  -e PUSHGO_DB_URL='postgres://user:pass@db:5432/pushgo' \
  -e PUSHGO_TOKEN='your_secure_token' \
  -e PUSHGO_PRIVATE_CHANNEL_ENABLED=true \
  -e PUSHGO_PRIVATE_TLS_CERT=/certs/fullchain.pem \
  -e PUSHGO_PRIVATE_TLS_KEY=/certs/privkey.pem \
  -v /etc/pushgo/certs:/certs:ro \
  ghcr.io/aldenclark/pushgo-gateway:latest

方式二：二进制直接运行

你可以直接在 Linux 服务器上运行预编译的二进制文件。

1. 下载二进制文件

curl -fL -o pushgo-gateway \
  https://github.com/AldenClark/pushgo-gateway/releases/latest/download/pushgo-gateway-amd64-musl
chmod +x pushgo-gateway

2. 源码编译 (可选)

如果你需要自定义编译或在非 Linux 平台运行：

cargo build --release -p pushgo-gateway
./target/release/pushgo-gateway --db-url <DB_URL>

3. Systemd 服务托管

在 Linux 上，建议使用 systemd 管理网关进程：

[Unit]
Description=PushGo Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pushgo
Group=pushgo
WorkingDirectory=/opt/pushgo-gateway
ExecStart=/opt/pushgo-gateway/pushgo-gateway \
  --http-addr 0.0.0.0:6666 \
  --private-channel-enabled \
  --db-url ${PUSHGO_DB_URL}

Environment=PUSHGO_DB_URL=postgres://user:pass@127.0.0.1:5432/pushgo
Environment=PUSHGO_PRIVATE_TLS_CERT=/etc/pushgo/certs/fullchain.pem
Environment=PUSHGO_PRIVATE_TLS_KEY=/etc/pushgo/certs/privkey.pem
Environment=PUSHGO_TOKEN=your_secure_token

Restart=always
RestartSec=2
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

---

核心配置参数

PushGo 主要通过环境变量进行配置。

环境变量	默认值	说明
PUSHGO_HTTP_ADDR	127.0.0.1:6666	HTTP API 与 WSS 监听地址
PUSHGO_DB_URL	(无，必填)	数据库 URL (支持 sqlite, postgres, mysql)
PUSHGO_TOKEN	(无)	公共 API 鉴权 Token (Bearer Token)
PUSHGO_PRIVATE_CHANNEL_ENABLED	false	是否开启私有传输通道 (实时推送)
PUSHGO_PUBLIC_BASE_URL	(无)	外部访问的基础 URL (OAuth/WSS 提示所需)
PUSHGO_TOKEN_SERVICE_URL	https://token.pushgo.dev	授权令牌交换服务地址

私有通道相关配置 (Private Channel)

环境变量	默认值	说明
PUSHGO_PRIVATE_TLS_CERT	(无)	私有通道 TLS 证书路径 (PEM)
PUSHGO_PRIVATE_TLS_KEY	(无)	私有通道 TLS 私钥路径 (PEM)
PUSHGO_PRIVATE_QUIC_BIND	127.0.0.1:5223	QUIC 本机监听地址 (UDP)
PUSHGO_PRIVATE_TCP_BIND	127.0.0.1:5223	Raw TCP 本机监听地址 (TCP)
PUSHGO_PRIVATE_TCP_TLS_OFFLOAD	false	Raw TCP 是否由外部代理卸载 TLS

---

Nginx / 反向代理配置

1. HTTP API 与 WSS

server {
    listen 443 ssl http2;
    server_name gateway.example.com;

    ssl_certificate     /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass http://127.0.0.1:6666;
    }
}

2. Raw TCP (Stream)

如果由网关处理 TLS（推荐）：

stream {
    server {
        listen 5223;
        proxy_pass 127.0.0.1:5223;
        proxy_timeout 600s;
    }
}

3. QUIC (UDP)

stream {
    server {
        listen 5223 udp;
        proxy_pass 127.0.0.1:5223;
        proxy_timeout 600s;
    }
}

---

关键说明

私有通道证书

QUIC 与 Raw TCP（非卸载模式）需要网关直接持有 TLS 证书。你可以使用 Let’s Encrypt 证书。证书必须包含在客户端连接时使用的域名。

端口与冲突 (QUIC)

PushGo 的 QUIC 传输层使用自定义 ALPN (pushgo-quic)，与 HTTP/3 不兼容。 如果你的 Nginx 已经在 443/udp 运行了 HTTP/3，私有通道 QUIC 必须使用不同的 UDP 端口（例如 5223/udp）。

数据库支持

• SQLite: sqlite:///data/pushgo.db?mode=rwc
• PostgreSQL: postgres://user:pass@host:port/db
• MySQL: mysql://user:pass@host:port/db

---

生产环境建议

1. 组合传输：建议同时启用 QUIC 和 Raw TCP，并将 WSS 作为防火墙受限环境下的备选。
2. 边缘安全：建议将 HTTP 端口监听在 127.0.0.1，仅通过 Nginx/LB 对外暴露。
3. 可观测性：设置 PUSHGO_OBSERVABILITY_PROFILE=ops 以开启运营指标统计。