Chitchatter 配置参数详解

目标：把 Chitchatter（main 分支 commit b0114d5）全部可配置项讲清楚——构建时环境变量（Vite 注入）、RTC 配置 API 服务端变量、静态托管层（Nginx）关键配置，以及嵌入 SDK 的构建期取值来源；每一项均给出默认值、生效方式与实测验证。已在 Ubuntu 22.04（Node.js v24.16.0）实测通过。

一、环境信息

本文所有命令与回显均在以下实测环境中执行：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Node.js：v24.16.0（npm 11.13.0）
• Chitchatter：main 分支 commit b0114d52eb786d240ef3a9d2b3691b215e29dbf0（项目无正式版本号，package.json 中 version 为 0.0.0）
• 源码路径：/opt/chitchatter；构建产物部署于 /var/www/chitchatter，由 Nginx 1.18.0 托管（HTTPS 443）
• RTC 配置 API：simple-api-server.js（仓库自带），监听 127.0.0.1:3003，由 systemd 托管

二、前置条件

阅读本文前需要一份已构建的 Chitchatter 源码树（含 node_modules）。从零完成的完整步骤见本专栏《Ubuntu 22.04 安装 Chitchatter 指南》篇；最低限度地，确认以下两点即可跟随本文操作：

cd /opt/chitchatter && git rev-parse --short HEAD && ls dist/sdk.js

实测回显：

b0114d5
dist/sdk.js

三、参数查看与修改方式

Chitchatter 是纯前端单页应用，没有运行时配置文件：所有前端配置都是「构建时」经 Vite 注入到静态产物里的环境变量，改任何一项都必须重新执行 npm run build 并重新发布 dist/。唯一的例外是随仓库附带的 RTC 配置 API（simple-api-server.js）——它是独立 Node 进程，配置经进程环境变量注入，改完重启进程即可。

三类配置的修改入口：

⚠️ 注意：Vite 会自动读取源码根目录的 .env 文件（仓库内附带的 .env 是官方注释模板，含全部可配项说明）。命令行前置变量（如 VITE_ROUTER_TYPE=hash npm run build）优先级高于 .env 文件。

四、参数总览

全部可配置项一览（来源：源码 src/config/*、sdk/sdk.ts、simple-api-server.js 与仓库 .env 模板，逐项核对）：

关键结论：Chitchatter 自身配置面很小（前端 7 项 + API 3 项），其余「配置」都发生在托管层（HTTPS、SPA 回退、CORS 头）与源码常量（tracker 列表、社区房间列表）上。下文分类逐项详解。

五、核心参数分类详解

5.1 前端构建变量（VITE_*）

5.1.1 VITE_RTC_CONFIG_ENDPOINT：增强连接（TURN 下发）开关

这是自托管最重要的一项。Chitchatter 内置一个公共 TURN 服务器兜底（见 5.2），但生产环境应使用自己的 TURN；浏览器端在「设置 → Networking」里打开 Enhanced Connectivity 后，会从该端点拉取 RTC 配置。

源码行为（src/config/enhancedConnectivity.ts）：只有设置了该变量，设置页才出现 Networking 区域；不设置则功能彻底隐藏，只用兜底 TURN。

实测：构建时注入后，产物中可检索到端点字符串：

grep -c "api/get-config" /var/www/chitchatter/assets/Bootstrap-*.js | grep -v ":0"

实测回显（本文构建注入了 VITE_RTC_CONFIG_ENDPOINT=/api/get-config）：

/var/www/chitchatter/assets/Bootstrap-BuRYNN6P.js:1
/var/www/chitchatter/assets/Bootstrap-JKYa_DP9.js:1

取值可以是同源相对路径（推荐，如 /api/get-config，由 Nginx 反代到 API 进程），也可以是完整的跨域 URL（此时 API 的 CORS 白名单需覆盖你的站点，见 5.2）。

5.1.2 VITE_ROUTER_TYPE：路由模式

• browser（默认）：BrowserRouter，URL 干净（/public/<房间名>），但要求托管层支持 SPA 回退（见 5.3）；房间名会出现在 HTTP 请求路径里，服务器日志可见房间名。
• hash：HashRouter，房间名放在 # 之后（/#/public/<房间名>），不随 HTTP 请求发出，服务器看不到房间名；且任何静态文件服务器（对象存储、CDN）都能直接托管，无需回退规则。

非法取值会被忽略并回退 browser（源码 src/config/router.ts 有 console.warn 提示）。

实测构建一个 hash 版（产物发布到另一站点目录对比验证）：

cd /opt/chitchatter
VITE_ROUTER_TYPE=hash npm run build

构建产物部署到 8080 端口站点后验证页面可访问：

curl -s http://127.0.0.1:8080/ | grep -o '<title>[^<]*</title>'

实测回显：

<title>Chitchatter</title>

💡 技术拓展：单页应用的路由模式不止这两种名称背后的实现——常见方案对比：

方案	URL 形态	服务器配合	本文场景取舍
History/Browser 路由	/public/room	需要 SPA 回退规则	默认，URL 美观
Hash 路由	/#/public/room	不需要任何规则	隐私更好（房间名不出现在请求里）、静态托管零配置
Memory 路由	URL 不变	不需要	嵌入/测试场景，Chitchatter 未采用

注重隐私（不让托管服务器看到房间名）或托管到纯静态对象存储时选 hash；本文默认部署用 browser。

5.1.3 VITE_HOMEPAGE：首页与 SDK 默认根地址

两个作用：界面内「回首页」链接的目标；sdk.js 嵌入时 <chat-room> 未指定 root-url 属性时的默认站点根地址（源码 sdk/sdk.ts 的 defaultRoot）。

⚠️ 注意（实测踩坑）：构建脚本写死了取值来源——npm run build 实际执行 cross-env VITE_HOMEPAGE=$(npm pkg get homepage) vite build，即强制取自 package.json 的 homepage 字段（默认 https://chitchatter.im/），命令行环境变量无法覆盖。因此自托管站点若要让 sdk.js 默认指向自己，必须修改 package.json 的 homepage 后再构建；不改的话，嵌入方必须显式写 root-url 属性（实测不写的后果见《Chitchatter 嵌入集成使用指南》篇）。

5.1.4 VITE_GITHUB_REPO：仓库链接

界面左侧抽屉底部「GitHub」链接与 commit 链接的拼接前缀（src/components/Shell/Drawer.tsx）。仓库 .env 模板中默认已设置为官方仓库地址；fork 后改成自己的仓库地址即可。

5.1.5 VITE_TRACKER_URL：自建 WebTorrent tracker

向 tracker 列表最前面追加一个自建 tracker 地址（源码 src/config/trackerUrls.ts 的 unshift），其余默认公共 tracker 仍保留为后备。官方注释说明：该变量本意服务 npm run dev 开发；自托管生产实例建议直接改源码里的 trackerUrls 数组常量。

⚠️ 注意：HTTPS 站点里的浏览器拒绝连接明文 ws:// tracker（混合内容限制），生产自建 tracker 必须以 wss:// 暴露（可用 Nginx 反代 WebSocket 实现，见《Ubuntu 22.04 安装 Chitchatter 指南》篇自建 tracker 一节）。

默认公共 tracker（Trystero 内置，实测从构建产物中检索）：

grep -o "wss://[a-zA-Z0-9./_-]*" /var/www/chitchatter/assets/Bootstrap-*.js | sort -u

实测回显：

/var/www/chitchatter/assets/Bootstrap-BuRYNN6P.js:wss://
/var/www/chitchatter/assets/Bootstrap-BuRYNN6P.js:wss://tracker.btorrent.xyz
/var/www/chitchatter/assets/Bootstrap-BuRYNN6P.js:wss://tracker.openwebtorrent.com
/var/www/chitchatter/assets/Bootstrap-JKYa_DP9.js:wss://
/var/www/chitchatter/assets/Bootstrap-JKYa_DP9.js:wss://tracker.btorrent.xyz
/var/www/chitchatter/assets/Bootstrap-JKYa_DP9.js:wss://tracker.openwebtorrent.com

5.1.6 VITE_STREAMSAVER_URL：文件下载服务

Chitchatter 的 P2P 文件分享经 StreamSaver.js 流式写盘，需要一个 mitm.html 中转页。默认使用作者托管的公共实例；自托管时把 StreamSaver.js 的 mitm.html 放到自己站点并改此变量（源码 src/config/streamSaverUrl.ts）。

5.1.7 VITE_API_BASE_URL：仅开发用

仅 npm run dev 开发模式生效（src/hooks/useTurnConfig.ts 里 import.meta.env.DEV 才读取），把 API 请求指到本地 simple-api-server.js（默认 http://localhost:3003）。生产构建忽略。

5.2 RTC 配置 API 服务端参数（simple-api-server.js）

仓库自带的 simple-api-server.js 是一个约 260 行的零依赖 Node HTTP 服务，只做一件事：GET /api/get-config 返回 RTC 配置（TURN 服务器），让前端「增强连接」功能动态获取 TURN 而不把凭据硬编码进前端产物。

5.2.1 RTC_CONFIG：Base64 编码的 RTCConfiguration

取值为 Base64 编码的 JSON，结构遵循 W3C RTCConfiguration（核心是 iceServers 数组）。生成方式（演示 TURN 账号 admin / 密码 q1w2e3r4，指向本机示例 TURN 地址）：

echo '{"iceServers":[{"urls":"stun:stun.l.google.com:19302"},{"urls":"turn:turn.chitchatter.local:3478","username":"admin","credential":"q1w2e3r4"}]}' | base64 -w 0

实测回显：

eyJpY2VTZXJ2ZXJzIjpbeyJ1cmxzIjoic3R1bjpzdHVuLmwuZ29vZ2xlLmNvbToxOTMwMiJ9LHsidXJscyI6InR1cm46dHVybi5jaGl0Y2hhdHRlci5sb2NhbDozNDc4IiwidXNlcm5hbWUiOiJhZG1pbiIsImNyZWRlbnRpYWwiOiJxMXcyZTNyNCJ9XX0=

服务端启动时经环境变量注入（systemd 单元片段）：

[Service]
Environment=RTC_CONFIG=eyJpY2VTZXJ2ZXJzIjpbeyJ1cmxzIjoic3R1bjpzdHVuLmwuZ29vZ2xlLmNvbToxOTMwMiJ9LHsidXJscyI6InR1cm46dHVybi5jaGl0Y2hhdHRlci5sb2NhbDozNDc4IiwidXNlcm5hbWUiOiJhZG1pbiIsImNyZWRlbnRpYWwiOiJxMXcyZTNyNCJ9XX0=
ExecStart=/usr/local/bin/node simple-api-server.js

实测验证（经 Nginx 同源反代调用）：

curl -sk https://localhost/api/get-config

实测回显：

{"urls":"turn:turn.chitchatter.local:3478","username":"admin","credential":"q1w2e3r4"}

注意返回体只含 TURN 那一项：源码在 iceServers 数组里 find 第一个 turn: 条目返回，STUN 项不下发（浏览器端另有默认处理）。若 RTC_CONFIG 未设置、Base64/JSON 非法或结构不含 TURN，服务端回退到内置公共 TURN 并打印告警日志：

{"urls":["turn:relay1.expressturn.com:3478"],"username":"efQUQ79N77B5BNVVKF","credential":"N4EAUgpjMzPLrxSS"}

（该回退值硬编码在 simple-api-server.js 第 48-52 行，是作者购买的公共 ExpressTURN 实例，有速率限制，生产必须用自己的。）

5.2.2 PORT 与绑定地址

PORT 环境变量控制监听端口，默认 3003；绑定地址写死 127.0.0.1（源码 server.listen(PORT, '127.0.0.1')），即设计上只允许本机反代访问，不直接对公网开放。

5.2.3 CORS_ALLOW_ALL 与来源白名单

默认严格模式：仅白名单内 Origin（https://chitchatter.im、官方 Vercel 预览域、localhost:3000/3001/3003）会被回显到 Access-Control-Allow-Origin，其余一律回落为 https://chitchatter.im。自托管并跨域调用 API 时有两个选择：同源反代（推荐，前端用相对路径 /api/get-config，根本不触发 CORS）；或设 CORS_ALLOW_ALL=true 放开为 *（源码明确注释为 DEBUG MODE，不安全，仅限调试）。

端点行为实测矩阵：

curl -sk https://localhost/api/get-config            # GET，正常
curl -sk -X POST -o /dev/null -w "%{http_code}\n" https://localhost/api/get-config
curl -sk -o /dev/null -w "%{http_code}\n" https://localhost/api/nope

实测回显：

{"urls":"turn:turn.chitchatter.local:3478","username":"admin","credential":"q1w2e3r4"}

405
404

即：仅支持 GET，非 /api/get-config 路径一律 404。

5.3 托管层（Nginx）关键配置

Chitchatter 本体无服务器配置，但托管层有三处配置错了功能就坏的点，本文实测站点配置如下（完整从零配置见《Ubuntu 22.04 安装 Chitchatter 指南》篇）：

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;   # ① 强制 HTTPS
}

server {
    listen 443 ssl;
    server_name _;

    ssl_certificate     /etc/ssl/certs/chitchatter.crt;
    ssl_certificate_key /etc/ssl/private/chitchatter.key;

    root /var/www/chitchatter;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;    # ② SPA 回退（browser 路由必需）
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3003;    # ③ RTC 配置 API 同源反代
        proxy_set_header Host $host;
    }

    location = /sdk.js {
        add_header Access-Control-Allow-Origin *;   # ④ 允许第三方站点引用 SDK
        add_header Cache-Control "no-cache";
    }

    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
}

逐项说明：

实测验证（HTTP 跳转、HTTPS 首页、SDK 头）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost/
curl -sk https://localhost/ | grep -o '<title>[^<]*</title>'
curl -skI https://localhost/sdk.js | grep -iE "access-control|cache-control"

实测回显：

301
<title>Chitchatter</title>
Access-Control-Allow-Origin: *
Cache-Control: no-cache

5.4 构建期常量（改源码，不属于变量）

以下「配置」没有环境变量入口，只能改源码后重新构建，列出供评估：

六、生产配置模板

适用场景：单台 2C4G 云主机，Ubuntu 22.04，HTTPS 自托管，自有 TURN，面向小团队私密沟通（日活数十人量级；静态托管几乎不占资源，瓶颈在 TURN 带宽）。

1. 构建变量（一次性写入 .env 或构建命令行）：

# /opt/chitchatter/.env
VITE_RTC_CONFIG_ENDPOINT=/api/get-config
VITE_ROUTER_TYPE=browser
VITE_GITHUB_REPO="https://github.com/jeremyckahn/chitchatter"
# 并把 package.json 的 "homepage" 改为你的站点根地址，例如：
# "homepage": "https://chat.example.com/",

2. API 服务端 systemd 环境（/etc/systemd/system/chitchatter-api.service）：

[Service]
Environment=RTC_CONFIG=<上一步 base64 生成的值>
Environment=PORT=3003
ExecStart=/usr/local/bin/node simple-api-server.js

3. 托管层：按 5.3 的 Nginx 配置，证书换正式证书（Let's Encrypt 或企业 CA 均可）。

改完备三项验证（全部实测命令）：curl -sk https://<域名>/ | grep '<title>Chitchatter</title>'（站点）、curl -sk https://<域名>/api/get-config（TURN 下发）、grep -c "api/get-config" /var/www/chitchatter/assets/Bootstrap-*.js（构建注入）。

七、常见问题

Q1：改了 .env 后页面行为没有变化？ VITE_* 是构建时注入的，改完必须重新 npm run build 并把新 dist/ 发布到站点目录；仅刷新浏览器无效。验证是否注入成功：grep -c "你的端点串" /var/www/chitchatter/assets/Bootstrap-*.js。

Q2：设置页里找不到「Networking / Enhanced Connectivity」开关？ 构建时没有设置 VITE_RTC_CONFIG_ENDPOINT（源码行为：未设置则功能整体隐藏）。重新构建并注入该变量，同时确认 API 端点可用（curl 返回 TURN JSON）。

Q3：VITE_HOMEPAGE 设了环境变量为什么不生效？ 构建脚本 cross-env VITE_HOMEPAGE=$(npm pkg get homepage) 会用 package.json 的 homepage 字段覆盖命令行变量。要么改 package.json 的 homepage，要么在嵌入侧用 root-url 属性显式指定（见《Chitchatter 嵌入集成使用指南》篇）。

Q4：/api/get-config 返回的 JSON 里没有我配的 STUN 服务器？ 正常现象：服务端只返回 iceServers 中第一个 turn: 条目（simple-api-server.js 的 find 逻辑），STUN 项不下发。

Q5：HTTPS 站点里自建 tracker 连不上？ 浏览器混合内容限制，ws:// 在 HTTPS 页面被拦截。tracker 必须经 wss:// 暴露（Nginx 反代 WebSocket 加 Upgrade/Connection 头），并确认 VITE_TRACKER_URL 用的是 wss:// 地址。

Q6：CORS_ALLOW_ALL=true 能用于生产吗？ 不能。源码注释明确标注为 DEBUG MODE（INSECURE）。生产用同源反代（/api/ 反代到 127.0.0.1:3003）彻底回避 CORS。

八、参考链接

• 源码仓库（含 .env 官方注释模板）：https://github.com/jeremyckahn/chitchatter
• Vite 环境变量机制：https://vite.dev/guide/env-and-mode
• W3C RTCConfiguration 规范：https://www.w3.org/TR/webrtc/#rtcconfiguration-dictionary
• Trystero（信令抽象，含默认 tracker 列表）：https://github.com/dmotz/trystero
• StreamSaver.js（mitm.html 配置说明）：https://github.com/jimmywarting/StreamSaver.js

本专栏其他篇目：《Chitchatter 介绍与选型指南》《Ubuntu 22.04 安装 Chitchatter 指南》《Chitchatter Docker Compose 部署指南》《Chitchatter 嵌入集成使用指南》。