跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
部署与云服务

relay-server-config

Full environment-variable / flag reference for configuring the portal-tunnel relay-server (cmd/relay-server), plus how config is embedded and how Docker/Compose deploys it. Use when configuring, deploying, or debugging a relay.

gosuda · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add gosuda/portal-tunnel --skill relay-server-config

技能说明


name: relay-server-config description: Full environment-variable / flag reference for configuring the portal-tunnel relay-server (cmd/relay-server), plus how config is embedded and how Docker/Compose deploys it. Use when configuring, deploying, or debugging a relay.

relay-server configuration

Entrypoint cmd/relay-server/main.go, dispatched by utils.RunCommands (""/serve → serve, help). Every flag has an env fallback parsed by utils.{String,Bool,Int}FlagEnv at flag-init time (utils/cmd.go); flags are declared in main.go ~79-117. --help shows usage/examples only, not flags.

Core env vars / flags (default)

EnvDefaultPurpose
PORTAL_URLhttps://localhostportal base URL (--portal-url)
PORTAL_FRONTEND_DIRemptycustom SPA dir; empty = embedded (--frontend-dir)
IDENTITY_PATH./.portal-certsidentity/cert + policy.json dir (--identity-path)
API_PORT4017HTTPS API + frontend (--api-port)
SNI_PORT443public SNI ingress (--sni-port) — cannot bind unprivileged; override locally
WIREGUARD_PORT51820(--wireguard-port)
EMBEDDED_DNS_PORT53embedded authoritative DNS (--embedded-dns-port) — default provider; needs 53/tcp+udp and CAP_NET_BIND_SERVICE in containers
ADMIN_TOKENemptybearer token for admin/policy APIs (--admin-token)
LANDING_PAGE_ENABLEDfalse(--landing-page-enabled)
DISCOVERYfalseenable gossip; needs BOOTSTRAPS (--discovery)
BOOTSTRAPSemptycomma-separated bootstrap relay URLs (--bootstraps)
TRUST_PROXY_HEADERSfalsetrust XFF etc. (--trust-proxy-headers)
TRUSTED_PROXY_CIDRSempty(--trusted-proxy-cidrs)
UDP_ENABLED / TCP_ENABLEDfalsenon-HTTP lease transports
MIN_PORT / MAX_PORT0 / 0lease port range; 0 disables
PPROF_ENABLED / PPROF_ADDRfalse / 127.0.0.1:6060pprof
X402_ENABLED / X402_TESTNET / X402_PAY_TOfalse / false / emptymounts facilitator under /api/x402 only when enabled

Embedded DNS is the default ACME_DNS_PROVIDER (empty value): EMBEDDED_DNS_PORT (default 53). External provider creds remain env-bound: ACME_DNS_PROVIDER, CLOUDFLARE_TOKEN, GCP (GCP_PROJECT_ID+aliases, GCP_MANAGED_ZONE+aliases), Hetzner (HETZNER_API_TOKEN/HCLOUD_TOKEN), AWS Route53 (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN/AWS_REGION→defaults us-east-1 downstream/AWS_HOSTED_ZONE_ID/AWS_DNSSEC_KMS_KEY_ARN), VULTR_API_KEY, NJALLA_TOKEN, ENS_GASLESS_ENABLED (unsupported with embedded). Never hardcode these — reference as env vars / secrets.

Reserved API surface (types/paths.go)

Root-host trees that must never fall through to the SPA: types.ReservedRootPrefixes = /api, /sdk, /discovery, /v1. x402 public paths /x402/prepare, /x402/client.js; relay facilitator /api/x402/{supported,verify,settle}. Discovery: /discovery, /discovery/announce (only when DISCOVERY=true).

Admin/policy API

GET/POST /api/policy with Authorization: Bearer $ADMIN_TOKEN. POST requires the FULL settings object (partial bodies → 400 invalid_mode). Persists to $IDENTITY_PATH/policy.json.

Config embedding & Docker

  • config.toml (version/protocol) and registry.json (default relays) are embedded via manifest.go and parsed in types/types.go.
  • docker-compose.yml runs ghcr.io/gosuda/portal:2, publishes TCP 443 + TCP/UDP 53 (embedded DNS, cap_add: NET_BIND_SERVICE) + UDP WireGuard port, and passes the above env vars.
  • Dockerfile: Node 22 stage builds the frontend into cmd/relay-server/dist/app, then make build-server-bin compiles the Go relay.