会话安全与 HTTP 代理升级说明¶

本变更随当前源码发布，具体发布版本以根目录 VERSION 为准。

数据库与登录态¶

升级前备份数据库，使用 draarl -c config.yaml -auto-migrate 执行迁移，再启动其它实例。本次 schema 版本为 3：users.session_version 默认 1，并幂等创建默认公共频道 999。重复迁移不会覆盖已有频道；已有 999 必须是启用的实体公共频道，启动自检会拒绝不符合条件的数据。该频道可改名和备注，但不能删除、停用或设为私有。

旧 access、discovery JWT 和历史 refresh 记录不再接受，升级后所有浏览器及使用 JWT 的客户端需要重新登录。普通设备密码协议不受 JWT 格式变化影响。JWT 身份使用不可变用户 ID（sub），用户名不再作为身份主键。改名、角色或审批变更、禁用及改密码会递增会话版本，旧 access/refresh/discovery 会失效。 HTTP/discovery 认证读取数据库当前用户状态，不使用进程内资料缓存，以免其它实例的变更延迟生效。因此认证请求会增加数据库读取；扩容时应根据实测配置连接池和数据库容量。现有已建立的实时连接仍沿用已有路由撤销机制；本变更不会增加每个音频数据包的数据库查询。多实例部署应协调更新全部中心实例，避免旧实例继续接受旧格式令牌。

HTTP 可信反代¶

直连服务保持默认值：

System:
    HTTPTrustedProxyCIDRs: []

仅将实际 HTTP 反向代理的来源地址列入名单。例如 Nginx 与服务在同一主机且通过 IPv4 回环访问：

System:
    HTTPTrustedProxyCIDRs:
        - "127.0.0.1/32"

Docker 场景填入实际反代容器的固定地址或其隔离网络的最小网段，写入持久化 config.yaml 后重启。不要使用 0.0.0.0/0 或把任意客户端所在网段列为代理。此字段独立于 UDP 的 ProxyTrustedCIDRs。只有可信来源的 HTTP 转发头参与客户端 IP 和 HTTPS Cookie 判定。反代必须覆盖 X-Forwarded-Proto，并正确建立 X-Forwarded-For 链；直连客户端伪造这些头不会改变限流 IP 或 Cookie 的 Secure 属性。

浏览器麦克风和 HTTPS¶

公网/局域网 IP 的 HTTP 页面无法取得浏览器麦克风。将站点通过 HTTPS 发布，并同步修改 Web.FrontendURL、Web.AllowedOrigins 和对象存储浏览器地址；WebSocket 由 HTTPS 页面使用 WSS。开发时可通过 http://localhost 访问。页面会说明不安全上下文的限制，并禁用按钮及键盘 PTT。音频播放与文字消息仍按浏览器支持情况使用，不能把麦克风限制当作全部音频播放不可用。

通联日志编辑契约¶

更新 API：省略字段表示保持原值，空字符串清除可选文本；功率 null 清除，0 保存为零。必填呼号/模式不能显式清空，时间必须符合 2006-01-02 15:04:05，更新频率必须大于零。客户端需要避免在保存时把空 RST 或零值自动回填为默认值。