Galene 1.2 配置参数详解

目标：逐项详解 Galene 1.2 的三层配置体系——galene 主程序命令行参数、全局配置 data/config.json、会议室配置 groups/*.json（含权限与密码格式、外部 TURN 的 ice-servers.json），并给出生产配置模板。字段定义已对照 1.2.1 源码（group/group.go、group/description.go）核实，示例均在 Ubuntu 24.04.5 LTS + Galene 1.2.1 实测通过。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS，x86_64
• 组件版本：Galene 1.2.1
• 安装布局：/opt/galene/（galene 二进制、static/、data/、groups/、recordings/），systemd 单元 galene.service
• 配置文件：/opt/galene/data/config.json（全局）、/opt/galene/groups/<组名>.json（会议室）、/opt/galene/data/ice-servers.json（外部 TURN，可选）
• 管理工具：galenectl（自签名证书环境命令需带 -insecure）

二、前置条件

• 已按《Ubuntu 24.04 安装 Galene 1.2 指南》完成安装并能 systemctl status galene 看到 active (running)。
• 已完成 galenectl initial-setup（生成 data/config.json）。
• 本文示例管理员账号 admin / q1w2e3r4（仅测试环境使用）。

三、参数查看与修改方式

Galene 的配置分三层，修改方式各不相同：

查看启动参数完整清单（实测回显）：

/opt/galene/galene -help

Usage of /opt/galene/galene:
  -cpuprofile file
    	store CPU profile in file
  -data directory
    	data directory (default "./data/")
  -groups directory
    	group description directory (default "./groups/")
  -http address
    	web server address (default ":8443")
  -insecure
    	act as an HTTP server rather than HTTPS
  -mdns
    	gather mDNS addresses
  -memprofile file
    	store memory profile in file
  -mutexprofile file
    	store mutex profile in file
  -recordings directory
    	recordings directory (default "./recordings/")
  -relay-only
    	require use of TURN relays for all media traffic
  -static directory
    	web server root directory (default "./static/")
  -turn address
    	built-in TURN server address ("" to disable) (default "auto")
  -udp-range port
    	UDP port (multiplexing) or port1-port2 (range)

四、参数总览

4.1 启动参数总览

4.2 全局配置 data/config.json 字段总览

4.3 会议室配置 groups/<组名>.json 字段总览

五、核心参数分类详解

5.1 网络与监听（-http、-turn、-udp-range、-insecure、-relay-only）

• -http :8443：Web 服务地址。改成 :443 需 root 或 capability；反代场景常保持 8443。
• -turn：内置 TURN（仅 IPv4）。取值行为：
  • auto（默认）：无 data/ice-servers.json 时等同 :1194，有则等同关闭；
  • :1194：监听本机所有公网 IPv4 地址的 1194/TCP+UDP（有公网 IP 时的推荐值）；
  • 203.0.113.1:1194：监听本机全部地址，但向客户端通告指定地址（NAT + 端口映射场景）；
  • ""：关闭内置 TURN，改用 ice-servers.json 中的外部 TURN。
• -udp-range：收敛媒体 UDP 端口。-udp-range 20000-40000 限定范围（建议数千以上跨度）；-udp-range 10000 表示只用单端口并在用户态解复用。便于防火墙精细化放行。
• -insecure：以纯 HTTP 运行。仅当上游有反向代理终结 TLS 时使用；公网直跑绝不要开。
• -relay-only：强制全部媒体走 TURN 中继，牺牲性能换最严格的连通性（高安全内网场景）。

💡 技术拓展：NAT 穿透技术不止 TURN 一种。常见选项——

技术	原理	代价	适用
STUN	探测 NAT 后的公网映射地址，打洞直连	免费、低延迟	大多数家用/办公 NAT
TURN	服务器中继全部媒体流	消耗服务器带宽	对称型 NAT / 严格防火墙
ICE	自动在 host/srflx/relay 候选中择优	协议框架（非独立服务）	WebRTC 的标准机制，贯穿始终

Galene 内置 TURN 兼做 STUN；本文实验环境因 NAT 无公网地址，实测日志出现 TURN: no public addresses，生产上要么放行 1194，要么配置外部 TURN（见 5.9）。

5.2 存储目录（-data、-groups、-recordings、-static）

四个目录默认值均为相对路径 ./，因此 systemd 单元的 WorkingDirectory=/opt/galene 与默认参数配合即得 /opt/galene/data 等布局。注意 data/ 内的 config.json、cert.pem、key.pem、var/tokens.jsonl 都是敏感文件，官方包内自动设为属主 0600；备份 data/var/tokens.jsonl 无需停机。

5.3 诊断参数（-cpuprofile、-memprofile、-mutexprofile）

传入文件路径即开启对应 pprof 采样，退出时写文件，用 go tool pprof <文件> 分析。仅排障时临时加在 ExecStart 上，常态关闭。

5.4 全局配置 data/config.json

实测环境生成的完整文件：

{
    "writableGroups": true,
    "users": {
        "admin": {
            "password": {
                "type": "bcrypt",
                "key": "$2a$12$BaXbi3neOCI89tHJdmZVCOxxmePW12.ApiWaIp342cd36fYDuSPX2"
            },
            "permissions": "admin"
        }
    }
}

逐项说明：

• users：服务器级管理员（可调用管理 API、被 galenectl 使用）。密码永远存哈希，不写明文。
• writableGroups：true 时 galenectl 可建/改/删会议室；设为 false 后 API 只读，会议室只能手工编辑 groups/ 文件管理。
• canonicalHost：例如 "galene.example.org"，用户用 IP 或别名访问时被重定向到规范名。
• proxyURL：反代场景的外部根 URL，如 "https://galene.example.org/"。
• allowOrigin/allowAdminOrigin：把 Galene 客户端嵌入第三方站点（iframe/自有前端）时配置跨域来源。

5.5 会议室展示与生命周期参数

以一个实测公开组为例（galenectl show-group -group city-watch 回显）：

{
    "description": "示例公开会议组",
    "displayName": "City Watch 会议室",
    "max-clients": 20,
    "public": true
}

• public: true 使该组出现在服务器首页（实测 https://localhost:8443/public-groups.json 返回含此组的数组，含 location、endpoint、displayName、clientCount 字段）。
• max-clients 控制人数上限；max-history-age（秒）控制聊天历史保留，默认 14400。
• not-before/expires 用于「限时会议」：值形如 "2026-11-01T09:00:00+08:00"。
• redirect 可把废弃组指向新地址而不删除。

5.6 用户与权限（users、wildcard-user、permissions）

users 把用户名映射到「密码 + 权限」。实测组文件节选：

"users": {
    "admin": {"password": {"type": "bcrypt", "key": "$2a$08$mkxddgxf2BR0DFNuD66OfO7xOGrhoSE8WynRvgC2Gv4brIMQ8/bte"}, "permissions": "op"},
    "fred":  {"password": {"type": "bcrypt", "key": "$2a$08$vpnc0uvQR6PWFnZXNrzGNuNc.4VU2b82CzngTHnOFTjCgtY9Dbfai"}, "permissions": "present"}
},
"wildcard-user": {"password": {"type": "bcrypt", "key": "$2a$08$.wBpn6icYV6GOk3grnyuVuzf4CWyRAp.kBYicLCFhhNI2/vGDUiM2"}, "permissions": "present"}

权限简写（推荐，源码 permissionsMap 定义）：

⚠️ 注意：permissions 也接受内部原子权限数组（如 ["present","message"]），但官方不推荐——原子权限随版本变动，简写更稳定。

wildcard-user 是「未登记用户名」的兜底规则：配固定密码则「任意用户名 + 统一口令」；配 {"type":"wildcard"} 密码则「任意用户名 + 任意口令」的完全开放会议：

galenectl -insecure create-user -group city-watch -wildcard
galenectl -insecure set-password -group city-watch -wildcard -type wildcard

5.7 密码哈希格式与外部认证

password 字段支持四种形态：

手工生成哈希（实测回显）：

galenectl hash-password -password q1w2e3r4                    # 默认 bcrypt
galenectl hash-password -password q1w2e3r4 -type pbkdf2       # pbkdf2

{"type":"bcrypt","key":"$2a$08$IEWT33vBYyKmV5IfOX8hXO3d49RO64p50Zmb6dfdlCcMpps8bube."}
{"type":"pbkdf2","hash":"sha-256","key":"0928ea6b06c296415c5a799cbe8e8afafc2e7ae1c1455f4e6b51fa9a42a176e0","salt":"8b4f020bc5ef36df","iterations":4096}

外部认证三件套：authKeys（JWK 公钥数组，须显式指定 alg）、authServer（认证服务器 URL，客户端拿到口令后自行向认证服务器换令牌，口令不经过 Galene）、authPortal（认证门户 URL，客户端先跳转门户再携 username+token 跳回）。用于对接 LDAP/OAuth2，官方提供 galene-ldap 与 Python 示例认证服务器。

5.8 媒体编解码（codecs）

codecs 数组限定组内可用编解码器，默认 ["vp8","opus"]。可选值：

示例（启用 VP9 与 AV1 的回退链）："codecs": ["av1","vp9","vp8","opus"]。

5.9 外部 TURN：data/ice-servers.json

服务器在 NAT 后（实测日志 TURN: no public addresses）时，把 -turn 设为 ""（或保持 auto）并提供本文件。单 TURN 示例：

[
    {
        "urls": ["turn:turn.example.org:443", "turn:turn.example.org:443?transport=tcp"],
        "username": "galene",
        "credential": "secret"
    }
]

配合 coturn 的 use-auth-secret 时加 "credentialType": "hmac-sha1"。可配置多个 TURN 做冗余，ICE 自动择优。文件存在且内置 TURN 开启时，优先使用外部服务器。

六、生产配置模板

适用画像：2C4G 小规格服务器、有公网 IP、50 人以内的团队日常会议。

/opt/galene/data/config.json：

{
    "writableGroups": true,
    "canonicalHost": "galene.example.org",
    "users": {
        "admin": {
            "password": {"type": "bcrypt", "key": "$2a$12$<用 galenectl initial-setup 生成>"},
            "permissions": "admin"
        }
    }
}

/opt/galene/groups/team.json（内部周会室）：

{
    "displayName": "团队周会",
    "description": "每周一例会",
    "public": true,
    "max-clients": 50,
    "max-history-age": 14400,
    "allow-recording": true,
    "codecs": ["vp8", "opus"],
    "users": {
        "admin": {"password": {"type": "bcrypt", "key": "<bcrypt 哈希>"}, "permissions": "op"}
    },
    "wildcard-user": {"password": {"type": "bcrypt", "key": "<bcrypt 哈希>"}, "permissions": "present"}
}

systemd ExecStart 建议：/opt/galene/galene -http :8443 -turn :1194 -udp-range 20000-40000，防火墙放行 8443/TCP、1194/TCP+UDP、20000-40000/UDP。

七、常见问题（FAQ）

Q1：改了 config.json / 组 JSON 需要重启吗？

不需要。官方明确两层 JSON 均实时加载（实测改组定义后立即 show-group 可见新值）。只有启动参数（-http、-turn 等）需要 systemctl restart galene。

Q2：writableGroups 设为 false 后 galenectl 还能做什么？

只读操作（list-groups、show-group、list-users、list-tokens）可用；一切写操作（create/update/delete）被拒绝。此时管理会议室靠手工编辑 groups/ 文件。

Q3：公开组设置了 public: true 但首页看不到？

检查组名是否在 URL 中可访问（curl -sk https://<主机>:8443/public-groups.json 应列出该组）；注意 redirect 组与已过期（expires）组不展示。

Q4：-udp-range 设单端口和设范围有何区别？

单端口（如 -udp-range 10000）由服务器在用户态解复用，最省防火墙规则但吞吐略低；范围方式每路流独占端口，性能更好。官方提示该机制尚在完善，日志中看到使用其他端口属正常。

Q5：如何彻底关闭内置 TURN？

ExecStart 加 -turn ""，并提供 data/ice-servers.json（否则无公网直达路径的客户端无法连通媒体）。

八、参考链接

• 官方管理手册（源码内 galene.md、含 Group description reference）：https://github.com/jech/galene
• 管理 API 说明（galene-api.md）：https://github.com/jech/galene/blob/master/galene-api.md
• 站内文档：《Galene 1.2 介绍与选型指南》https://www.quzuo.net/document/OS394POo9wtA、《Ubuntu 24.04 安装 Galene 1.2 指南》https://www.quzuo.net/document/JmXRH0x02qtd、《Galene 1.2 Docker Compose 部署指南》https://www.quzuo.net/document/8hoLi6NGyKYn