Galene 1.2 常用 CLI 命令与工具详解

目标：详解 Galene 1.2 的两个命令行工具——galene（服务器主程序，13 个启动参数）与 galenectl（管理 CLI，18 个子命令），附管理 API 的 curl 速查。全部命令、参数默认值与回显均来自 Ubuntu 24.04.5 LTS + Galene 1.2.1 实测。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS，x86_64
组件版本：Galene 1.2.1（主程序 galene、管理工具 galenectl 同版本配套编译）
安装路径：/opt/galene/galene、/usr/local/bin/galenectl
服务托管：galene.service（systemd），监听 8443/TCP（HTTPS）
galenectl 客户端配置：/root/.config/galene/galenectl.json
演示账号：admin / q1w2e3r4（仅测试环境）；演示会议室：city-watch（主持人组）、unseen-university（自动子组）

二、工具概览

工具	角色	作用对象	工作方式
`galene`	服务器主程序	进程本身	命令行参数控制监听、目录、TURN 等，常驻运行
`galenectl`	管理 CLI	会议室/用户/密码/令牌/管理员	通过 HTTPS 管理 API（`/galene-api/v0/`）远程操作，改 JSON 存储

分工原则：进程级设置找 galene 参数，业务对象（组/用户/令牌）找 galenectl。galenectl 不直接改文件，而是走 API，自带 ETag 乐观并发控制，比手工编辑 groups/*.json 更安全。

三、前置条件

服务已运行：systemctl is-active galene 返回 active。
已执行过 galenectl initial-setup（见 4.2），生成了客户端配置与服务器管理员。
自签名证书环境下，galenectl 每条命令需带全局参数 -insecure（否则报 x509: certificate is not valid for any names）。本文所有 galenectl 命令均带此参数。

四、galene 主程序

4.1 启动参数速查

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)

13 个参数的逐项含义与取值见《Galene 1.2 配置参数详解》；日常最常用的只有四个：-http（Web 地址）、-turn（内置 TURN）、-udp-range（收敛媒体端口）、-insecure（反代后纯 HTTP）。

4.2 运行方式

生产用 systemd 托管（实测单元文件）：

[Service]
Type=simple
User=galene
Group=galene
WorkingDirectory=/opt/galene
ExecStart=/opt/galene/galene
LimitNOFILE=65536
Restart=on-failure

改启动参数即改 ExecStart（如加 -turn :1194），随后 systemctl daemon-reload && systemctl restart galene。

4.3 验证与日志

systemctl is-active galene
ss -ltnp | grep 8443
journalctl -u galene --no-pager | tail -5

实测回显（NAT 环境的典型日志，属预期行为）：

active
LISTEN 0      4096               *:8443             *:*    users:(("galene",pid=3410,fd=6))
Oct 25 07:28:28 galene-server galene[3410]: 2026/10/25 07:28:28 TURN: no public addresses
Oct 25 07:28:48 galene-server galene[3410]: 2026/10/25 07:28:48 Relay test failed: i/o timeout
Oct 25 07:28:48 galene-server galene[3410]: 2026/10/25 07:28:48 Perhaps you didn't configure a TURN server?

五、galenectl 全局参数与连接配置

5.1 全局参数

galenectl -help 实测输出（节选：参数部分 + 子命令清单）：

/usr/local/bin/galenectl [option...] command [option...] [args...]
  -admin-password password
    	administrator password
  -admin-token token
    	administrator token
  -admin-username username
    	administrator username
  -config file
    	configuration file (default "/root/.config/galene/galenectl.json")
  -insecure
    	don't check server certificates
  -server url
    	server url

  create-group       create a group
  create-token       request a token
  create-user        create a user
  delete-group       delete a group
  delete-password    delete a user's password
  delete-token       delete a token
  delete-user        delete a user
  hash-password      generate a hashed password
  initial-setup      initial setup of Galene and galenectl
  list-groups        list groups
  list-tokens        list tokens
  list-users         list users
  revoke-token       revoke a token
  set-password       set a user's password
  show-group         show group definition
  update-group       change a group's definition
  update-token       change a token's permissions, etc.
  update-user        change a user's permissions

全局参数说明：

参数	默认	说明
`-server`	配置文件中的 server	服务器 URL，如 `https://localhost:8443`
`-config`	`~/.config/galene/galenectl.json`	客户端配置文件路径
`-admin-username` / `-admin-password`	配置文件中的值	管理员凭据（命令行传入优先于配置文件）
`-admin-token`	空	用管理令牌代替密码认证（1.2 新增）
`-insecure`	关	不校验服务器证书（自签名环境必加）

5.2 initial-setup：一次性初始化

galenectl -insecure -server https://localhost:8443 \
  -admin-username admin -admin-password q1w2e3r4 initial-setup

成功无输出，产出两个文件。客户端配置 /root/.config/galene/galenectl.json（实测）：

{
    "server": "https://localhost:8443",
    "admin-username": "admin",
    "admin-password": "q1w2e3r4"
}

之后常规命令可省略 -server/-admin-* 参数，只带 -insecure 即可（-config 参数可指定其他位置的配置文件，便于管理多台服务器）。

六、会议室管理

6.1 create-group：创建会议室

参数：-group <名>（必填）、-unrestricted-tokens（允许普通用户发令牌）、-auto-subgroups（自动子组）、-json（从标准输入读 JSON 模板）。

galenectl -insecure create-group -group city-watch
galenectl -insecure create-group -group unseen-university -auto-subgroups

成功无输出。auto-subgroups 组下访问 unseen-university/hex 这类子组地址时会按需自动创建子组。

JSON 模板方式（适合一次写好展示名、人数上限等；模板不允许包含 users/wildcard-user）：

echo '{"displayName":"City Watch 会议室","description":"示例公开会议组","public":true,"max-clients":20}' \
  | galenectl -insecure create-group -group city-watch -json

6.2 update-group：修改会议室

# 布尔开关直接给值
galenectl -insecure update-group -group city-watch -unrestricted-tokens=false

# JSON 模板增量合并（字段设 null 即删除该字段）
echo '{"displayName":"演示会议室","max-clients":10}' | galenectl -insecure update-group -group demo2 -json

⚠️ 注意：从标准输入读 JSON 必须带 -json，否则输入被静默忽略（实测不带时 show-group 仍返回 {}）。

6.3 show-group：查看组定义

galenectl -insecure show-group -group city-watch

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

输出为「脱敏」后的组定义 JSON（不含用户与密钥）。

6.4 list-groups：列出会议室

galenectl -insecure list-groups            # 全部
galenectl -insecure list-groups "city*"    # 支持通配过滤

city-watch
unseen-university

city-watch

6.5 delete-group：删除会议室

galenectl -insecure delete-group -group demo-room

成功无输出，组文件 groups/demo-room.json 同步删除，实时生效。

七、用户与密码管理

7.1 create-user / update-user：创建与修改用户

create-user 参数：-group、-user、-permissions（默认 present）、-wildcard（操作通配用户）、-json。

galenectl -insecure create-user -group city-watch -user admin -permissions op
galenectl -insecure create-user -group city-watch -user fred          # 默认 present
galenectl -insecure create-user -group city-watch -wildcard           # 通配用户
galenectl -insecure update-user -group city-watch -user fred -permissions message   # 改为仅聊天

权限简写：op（主持人）/ present（可发布音视频+聊天，默认）/ message（仅聊天）/ observe（仅观看）/ caption（字幕）/ admin（组管理）。

7.2 list-users：列出用户

galenectl -insecure list-users -l -group city-watch

admin        op
fred         present

-l 显示权限列；不加只列用户名。

7.3 set-password / delete-password：设置与删除密码

参数：-password（明文，服务端哈希存储）、-type（默认 bcrypt，可选 pbkdf2/wildcard）、-cost（bcrypt 强度，默认 8）、-iterations/-key/-salt（pbkdf2 参数，默认 4096/32/8）。

galenectl -insecure set-password -group city-watch -user admin -password q1w2e3r4
galenectl -insecure set-password -group city-watch -wildcard -type wildcard   # 开放会议：任意口令
galenectl -insecure delete-password -group city-watch -user fred              # 删除后该用户无法登录

成功均无输出。实测落盘的哈希形态（groups/city-watch.json 节选）：

"admin": {"password": {"type":"bcrypt","key":"$2a$08$mkxddgxf2BR0DFNuD66OfO7xOGrhoSE8WynRvgC2Gv4brIMQ8/bte"}, "permissions":"op"}

7.4 hash-password：离线生成密码哈希

不触达服务器，直接输出可粘贴进组 JSON 的哈希对象（实测两种算法回显）：

galenectl hash-password -password q1w2e3r4
galenectl hash-password -password q1w2e3r4 -type pbkdf2

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

7.5 delete-user：删除用户

galenectl -insecure delete-user -group city-watch -user fred
galenectl -insecure delete-user -group city-watch -wildcard     # 删除通配用户

八、令牌管理（邀请链接）

令牌即邀请链接中的 ?token=XXX，实现免密入会。Web 界面里主持人用 /invite 也能发，命令行适合批量与自动化。

8.1 create-token：创建令牌

参数：-group、-permissions（默认 present）、-duration（有效期，默认 24h0m0s）、-user（把用户名编码进令牌）、-include-subgroups（覆盖整个组层级）。

galenectl -insecure create-token -group city-watch -duration 2h -permissions present

hmrgaOUevEY

输出即令牌串。拼成邀请链接 https://<主机>:8443/group/city-watch/?token=hmrgaOUevEY，实测带令牌访问会议室页面返回 200。发「全服务器通杀」令牌：galenectl -insecure create-token -group '' -include-subgroups。

8.2 list-tokens：列出令牌

galenectl -insecure list-tokens -l -group city-watch

hmrgaOUevEY                      mp   2026-10-25 10:02:51

-l 显示权限缩写（mp = message+present）与到期时间；已吊销/过期的显示 (expired)：

-P9afPzieMg                      mp   (expired)

8.3 update-token / revoke-token / delete-token

galenectl -insecure update-token -group city-watch -token hmrgaOUevEY -duration 72h   # 改有效期/权限
galenectl -insecure revoke-token -group city-watch -token hmrgaOUevEY                 # 立即吊销（保留记录）
galenectl -insecure delete-token -group city-watch -token hmrgaOUevEY                 # 彻底删除记录

revoke 与 delete 的区别：revoke 使令牌失效但记录留在 data/var/tokens.jsonl（审计可查），delete 连记录一起删。

九、管理 API 速查（curl 实测）

galenectl 底层就是这套 API；写自动化脚本时可直接调用。认证用 HTTP Basic（config.json 里的 admin）或 Bearer 管理令牌。端点前缀 /galene-api/v0/，写操作用 ETag/If-Match 做乐观并发控制。

# 运行统计
curl -sk -u admin:q1w2e3r4 https://localhost:8443/galene-api/v0/.stats
# 组列表 / 组定义 / 用户列表
curl -sk -u admin:q1w2e3r4 https://localhost:8443/galene-api/v0/.groups/
curl -sk -u admin:q1w2e3r4 https://localhost:8443/galene-api/v0/.groups/city-watch/
curl -sk -u admin:q1w2e3r4 https://localhost:8443/galene-api/v0/.groups/city-watch/.users/

实测回显：

[{"name":"city-watch"}]

["city-watch","unseen-university"]

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

["admin","fred"]

常用端点速查：

端点	方法	用途
`/galene-api/v0/.stats`	GET	运行统计
`/galene-api/v0/.groups/`	GET	组列表
`/galene-api/v0/.groups/<组>/`	GET/PUT/DELETE	组定义（PUT 新建带 `If-None-Match: *`，修改带 `If-Match: <ETag>`）
`/galene-api/v0/.groups/<组>/.keys`	PUT/DELETE	组的外部认证 JWK 密钥
`/galene-api/v0/.groups/<组>/.users/`	GET	用户列表
`/galene-api/v0/.groups/<组>/.users/<名>`	GET/PUT/DELETE	用户定义（另有 `.empty-user`/`.wildcard-user` 特殊端点）
`/galene-api/v0/.groups/<组>/.users/<名>/.password`	PUT/POST/DELETE	密码（POST 传明文服务端哈希）
`/galene-api/v0/.groups/<组>/.users/<名>/.tokens/`	GET/POST	令牌列表/创建
`/galene-api/v0/.groups/<组>/.users/<名>/.tokens/<令牌>`	GET/PUT	单个令牌

十、注意事项

证书校验：自签名环境所有 galenectl 命令都要 -insecure；正式证书环境让 -server 用证书域名即可去掉。
配置文件优先级：命令行 -admin-*/-server 覆盖 galenectl.json 中的值；多服务器管理用 -config 切换配置文件。
密码不落明文：galenectl 只写哈希（bcrypt 默认 cost 8）；组文件里的 $2a$08$... 即哈希，不是明文。
并发安全：改组定义优先用 galenectl（API 有 ETag 乐观锁）；手工编辑文件虽实时生效，但与 API 写并发时可能互相覆盖。
删除不可逆：delete-group 连用户定义一起删，操作前用 show-group 留底。

十一、常见问题（FAQ）

Q1：Option "-admin-username" is required.

initial-setup 必须显式给 -admin-username（密码不给则交互式询问）。常规命令报同类错说明配置文件缺失，检查 ~/.config/galene/galenectl.json。

Q2：tls: failed to verify certificate: x509: certificate is not valid for any names

自签名证书未加 -insecure，或 -server 主机名与证书不符。加 -insecure 或换正式证书。

Q3：update-group 从标准输入改了 JSON 但没生效？

漏了 -json 参数，输入被忽略。正确写法：echo '{"max-clients":30}' | galenectl -insecure update-group -group <名> -json，随后 show-group 复核。

Q4：忘记管理员密码怎么办？

在服务器上重跑一次 initial-setup（覆盖 data/config.json 中同名管理员），或手工编辑 data/config.json 用 hash-password 生成的新哈希替换。

Q5：如何批量创建多个会议室？

galenectl 每条命令操作一个对象；批量场景写 shell 循环调用 create-group -json 喂入模板，或直接用管理 API（PUT + If-None-Match: *）。

十二、参考链接

官方管理手册（galene.md Server administration 章）：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 配置参数详解》https://www.quzuo.net/document/FKTseOpRUdt6