Ubuntu 22.04 安装 Chitchatter 指南
Ubuntu 22.04 从零部署 Chitchatter（main 分支 b0114d5）：Node.js 24 + 源码构建 + Nginx HTTPS 托管，含离线产物分发方案、RTC 配置 API 与自建 tracker 可选组件，全部命令实测。
Ubuntu 22.04 安装 Chitchatter 指南
目标：在 Ubuntu 22.04 上从零部署一套生产可用的 Chitchatter（main 分支 commit b0114d5）：Node.js 环境 → 源码构建 → Nginx HTTPS 托管，并可选启用 RTC 配置 API（增强连接）与自建 WebTorrent tracker。全部命令与回显均在真实环境逐条实测。
一、环境信息
本文所有命令与回显均在以下实测环境中执行：
- 操作系统：Ubuntu 22.04.5 LTS（x86_64，systemd 真机）
- Node.js：v24.16.0（npm 11.13.0，官方 tar.xz 安装至
/usr/local） - Nginx：1.18.0（Ubuntu 仓库版）
- Chitchatter：main 分支 commit
b0114d52eb786d240ef3a9d2b3691b215e29dbf0（项目无正式版本号，package.json中version为0.0.0，以 commit 为交付基线） - 源码路径：
/opt/chitchatter；站点目录：/var/www/chitchatter；监听 80（跳转）+ 443（HTTPS） - 可选组件：RTC 配置 API（
127.0.0.1:3003，systemd 托管）、自建 tracker（0.0.0.0:8000，systemd 托管）
💡 说明：Chitchatter 是纯前端单页应用，「安装」的本质是「构建静态产物 + 用 Web 服务器托管」。官方主推 Vercel 托管；自建时 Nginx 是最常用形态。
二、前置条件
- 一台 Ubuntu 22.04 服务器（root 或可 sudo 的账号），2GB 以上空闲磁盘（依赖安装 + 构建中间产物）；
- 80/443 端口空闲；
- 能访问 GitHub 与 npm 官方仓库（构建期联网）；生产环境另有公网域名与正式证书更佳（本文用自签证书演示，浏览器告警属预期）；
- WebRTC 音视频能力要求页面必须是 HTTPS（或 localhost），因此本指南直接以 HTTPS 为最终形态。
三、版本选型说明
Chitchatter 处于 pre-alpha 阶段、无正式版本号与发布节奏，官方仓库的 main 分支即交付物。选型结论：锁定一个具体 commit 作为部署基线，升级=换新 commit 重建。本文锁定 b0114d5（2026-10-23 提交，采集日期 2026-10-25 时为 main 最新）。
Node.js 版本要求：package.json 声明 engines.node >= 24（构建实测用 v24.16.0 通过）；npm 随 Node 自带。
四、方案 A：源码构建 + Nginx 托管（在线，推荐）
4.1 方案说明
官方事实标准路径：装 Node.js → 克隆源码 → npm ci 装依赖 → npm run build 出 dist/ → 拷给 Nginx 托管。适合可联网服务器，产物与官方站点同源。
4.2 安装基础环境
安装 Git、Nginx 与证书工具：
apt-get update
apt-get install -y git nginx openssl
实测回显（节选，已装过则显示为最新版）：
Reading package lists... Done
...
git is already the newest version (1:2.34.1-1ubuntu1.18).
nginx is already the newest version (1.18.0-6ubuntu14.21).
安装 Node.js v24（官方 tar.xz，避免发行版仓库版本过旧——Ubuntu 22.04 仓库仅 12.x）：
cd /root
curl -fsSLO https://nodejs.org/dist/v24.16.0/node-v24.16.0-linux-x64.tar.xz
tar -xJf node-v24.16.0-linux-x64.tar.xz -C /usr/local --strip-components=1
rm -f node-v24.16.0-linux-x64.tar.xz
node -v && npm -v
实测回显：
v24.16.0
11.13.0
⚠️ 网络说明：实测环境可直连 nodejs.org 与 GitHub。若下载慢或失败，可换国内镜像
https://npmmirror.com/mirrors/node/v24.16.0/node-v24.16.0-linux-x64.tar.xz，或走代理后再试；验证下载完整性的办法是tar -tJf <包名> | head能列出node-v24.16.0-linux-x64/bin/node等条目。
4.3 拉取源码与安装依赖
git clone https://github.com/jeremyckahn/chitchatter.git /opt/chitchatter
cd /opt/chitchatter
git checkout b0114d52eb786d240ef3a9d2b3691b215e29dbf0
实测回显（节选）：
Cloning into '/opt/chitchatter'...
Note: switching to 'b0114d52eb786d240ef3a9d2b3691b215e29dbf0'.
You are in 'detached HEAD' state. ...
💡 说明：
detached HEAD（游离头指针）是 checkout 具体 commit 的正常状态，表示当前不在任何分支上，对只读构建无影响。
安装依赖（npm ci 严格按 package-lock.json 安装，保证可复现）：
npm ci --no-audit --no-fund
实测回显（末尾）：
added 1612 packages in 15s
4.4 构建产物
注入 RTC 配置端点后构建（端点语义见「六、可选组件：RTC 配置 API」；不需要该功能时直接执行 npm run build 即可）：
cd /opt/chitchatter
VITE_RTC_CONFIG_ENDPOINT=/api/get-config npm run build
实测回显（节选首尾）：
> chitchatter@0.0.0 build
> npm run build:app && npm run build:sdk
vite v6.4.2 building for production...
✓ 13144 modules transformed.
...
dist/assets/Bootstrap-BuRYNN6P.js 1,793.03 kB │ gzip: 569.49 kB │ map: 7,008.06 kB
✓ built in 10.95s
> chitchatter@0.0.0 build:sdk
> cross-env VITE_HOMEPAGE=$(npm pkg get homepage) parcel build sdk/sdk.ts --no-content-hash
✨ Built in 978ms
dist/sdk.js 3.14 kB 53ms
确认产物：
du -sh dist && ls dist
实测回显：
17M dist
404.html CNAME assets favicon.ico index.html logo logo192.png ...
（完整列表还含 manifest.webmanifest、robots.txt、screenshots/、sdk.js、service-worker.js、sounds/ 等。）
⚠️ 注意：构建日志中
Some chunks are larger than 500 kB是 Rollup 的提示而非错误，Chitchatter 主包约 1.8MB（gzip 后约 570KB），纯聊天工具可接受，无需处理。
4.5 部署到 Nginx 并启用 HTTPS
拷贝产物到站点目录：
mkdir -p /var/www/chitchatter
cp -r /opt/chitchatter/dist/* /var/www/chitchatter/
生成自签证书（生产环境替换为正式证书，路径保持一致即可）：
openssl req -x509 -newkey rsa:2048 \
-keyout /etc/ssl/private/chitchatter.key \
-out /etc/ssl/certs/chitchatter.crt \
-days 3650 -nodes \
-subj "/C=CN/ST=Shanghai/L=Shanghai/O=quzuo/CN=chitchatter.local"
实测回显（密钥生成进度，节选）：
..+......+.....+.+......+..+.....+...+++++++++++++++++++++++++++++++++++++++
-----
创建站点配置 /etc/nginx/sites-enabled/chitchatter：
server {
listen 80;
server_name _;
return 301 https://$host$request_uri;
}
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;
}
location /api/ {
proxy_pass http://127.0.0.1:3003;
proxy_set_header Host $host;
}
location = /sdk.js {
add_header Access-Control-Allow-Origin *;
add_header Cache-Control "no-cache";
}
gzip on;
gzip_types text/css application/javascript application/json image/svg+xml;
}
关键项解读：try_files ... /index.html 是 SPA 回退，缺了它直接打开房间链接会 404；/api/ 反代把 RTC 配置 API 收进同源（不需要该功能可删除此段）；sdk.js 的 CORS 头供第三方页面嵌入使用。
校验配置并启动：
nginx -t
systemctl enable nginx
systemctl restart nginx
systemctl is-active nginx
实测回显：
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Executing: /lib/systemd/systemd-sysv-install enable nginx
active
4.6 验证
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 "HTTP|access-control"
openssl x509 -in /etc/ssl/certs/chitchatter.crt -noout -subject
实测回显：
301
<title>Chitchatter</title>
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
subject=C = CN, ST = Shanghai, L = Shanghai, O = quzuo, CN = chitchatter.local
浏览器访问 https://<服务器IP>/（自签证书会有安全提示，接受后）即可创建房间开始聊天。
五、方案 B：离线产物分发部署（内网/断网）
5.1 方案说明
目标服务器完全断网时，在一台可联网的构建机上完成方案 A 的 4.2~4.4（构建），只把 dist/ 产物打包送到目标机托管。产物是纯静态文件，目标机不需要 Node.js 与源码。
5.2 构建机打包产物
cd /opt/chitchatter
tar -czf /root/chitchatter-dist-b0114d5.tar.gz -C dist .
ls -lh /root/chitchatter-dist-b0114d5.tar.gz
实测回显：
-rw-r--r-- 1 root root 5.7M Oct 25 03:41 /root/chitchatter-dist-b0114d5.tar.gz
经 U 盘/内网通道把 tar 包送到目标机。
5.3 目标机部署与验证
目标机只需 Nginx（apt-get install -y nginx openssl，Ubuntu 仓库离线可用本地 apt 源/光盘源）：
mkdir -p /var/www/chitchatter
tar -xzf chitchatter-dist-b0114d5.tar.gz -C /var/www/chitchatter
ls /var/www/chitchatter
实测回显（节选）：
404.html CNAME assets favicon.ico index.html logo ...
之后照抄方案 A 的 4.5（证书 + 站点配置 + 启动）与 4.6（验证），回显一致。
六、可选组件：RTC 配置 API（增强连接）
Chitchatter 直连失败时靠 TURN 中继。默认内置一个公共 TURN（速率受限）；生产建议用自己的 TURN，并通过仓库自带的 simple-api-server.js 把 TURN 配置动态下发给浏览器（对应前端设置页的「Enhanced Connectivity」开关，需构建时注入 VITE_RTC_CONFIG_ENDPOINT，见 4.4）。
生成 Base64 配置（演示 TURN 账号 admin，密码 q1w2e3r4）：
echo '{"iceServers":[{"urls":"stun:stun.l.google.com:19302"},{"urls":"turn:turn.chitchatter.local:3478","username":"admin","credential":"q1w2e3r4"}]}' | base64 -w 0
实测回显：
eyJpY2VTZXJ2ZXJzIjpbeyJ1cmxzIjoic3R1bjpzdHVuLmwuZ29vZ2xlLmNvbToxOTMwMiJ9LHsidXJscyI6InR1cm46dHVybi5jaGl0Y2hhdHRlci5sb2NhbDozNDc4IiwidXNlcm5hbWUiOiJhZG1pbiIsImNyZWRlbnRpYWwiOiJxMXcyZTNyNCJ9XX0=
创建 systemd 单元 /etc/systemd/system/chitchatter-api.service（Environment= 值换上一步输出）：
[Unit]
Description=Chitchatter RTC config API server
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/chitchatter
Environment=RTC_CONFIG=eyJpY2VTZXJ2ZXJzIjpbeyJ1cmxzIjoic3R1bjpzdHVuLmwuZ29vZ2xlLmNvbToxOTMwMiJ9LHsidXJscyI6InR1cm46dHVybi5jaGl0Y2hhdHRlci5sb2NhbDozNDc4IiwidXNlcm5hbWUiOiJhZG1pbiIsImNyZWRlbnRpYWwiOiJxMXcyZTNyNCJ9XX0=
ExecStart=/usr/local/bin/node simple-api-server.js
Restart=on-failure
[Install]
WantedBy=multi-user.target
启动并验证：
systemctl daemon-reload
systemctl enable chitchatter-api
systemctl start chitchatter-api
systemctl is-active chitchatter-api
curl -sk https://localhost/api/get-config
实测回显：
active
{"urls":"turn:turn.chitchatter.local:3478","username":"admin","credential":"q1w2e3r4"}
返回 JSON 即 TURN 下发成功（服务端只返回 iceServers 中的 TURN 项，STUN 不下发，属正常）。参数细节见《Chitchatter 配置参数详解》篇 5.2 节。
七、可选组件：自建 WebTorrent tracker
默认信令走公共 tracker（wss://tracker.btorrent.xyz 等）。内网环境公网 tracker 不可达时，用依赖树里自带的 bittorrent-tracker 自建（npm ci 已装，无需额外安装）。
创建 systemd 单元 /etc/systemd/system/chitchatter-tracker.service：
[Unit]
Description=Chitchatter self-hosted WebTorrent tracker
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/node /opt/chitchatter/node_modules/.bin/bittorrent-tracker --port 8000
Restart=on-failure
[Install]
WantedBy=multi-user.target
启动并验证：
systemctl daemon-reload
systemctl enable chitchatter-tracker
systemctl start chitchatter-tracker
systemctl is-active chitchatter-tracker
curl -s http://127.0.0.1:8000/
实测回显：
Created symlink /etc/systemd/system/multi-user.target.wants/chitchatter-tracker.service → /etc/systemd/system/chitchatter-tracker.service.
active
d14:failure reason33:invalid action in HTTP request: /e
最后一行是 BitTorrent 协议对普通 HTTP GET 的报错回包——恰恰证明 tracker 已在 8000 端口正常应答。让浏览器使用它：重新构建时注入 VITE_TRACKER_URL（注意 HTTPS 站点必须用 wss://，需再经 Nginx 反代 WebSocket，取舍见《Chitchatter 配置参数详解》篇 5.1.5）。
八、方案对比与选择建议
| 维度 | 方案 A：源码构建 | 方案 B：离线产物分发 |
|---|---|---|
| 目标机需联网 | 是（构建期） | 否 |
| 目标机需 Node.js | 是 | 否 |
| 产物一致性 | 现场构建 | 与构建机完全一致（tar 包搬运） |
| 适用场景 | 可联网服务器 | 内网/断网/审计环境 |
| systemd 服务 | nginx（+ 可选 api/tracker） | 同左 |
建议：能联网一律选方案 A；内网环境选方案 B，构建机与目标机操作系统/架构无需一致（产物是纯静态文件）。
九、配置说明
常用运行时配置入口汇总（逐项语义与取值见《Chitchatter 配置参数详解》篇）：
- 站点配置：
/etc/nginx/sites-enabled/chitchatter（改后nginx -t && systemctl reload nginx）； - 证书：
/etc/ssl/certs/chitchatter.crt与/etc/ssl/private/chitchatter.key； - RTC API：
/etc/systemd/system/chitchatter-api.service的Environment=RTC_CONFIG=（改后systemctl daemon-reload && systemctl restart chitchatter-api）； - 前端变量（
VITE_*）：构建时注入，改动需重新构建并替换/var/www/chitchatter。
升级：更新 /opt/chitchatter 源码到新 commit → 重做 4.4 构建 → 替换 /var/www/chitchatter → 无需重启 Nginx（静态文件即时生效，建议浏览器强刷）。
十、常见问题
Q1：apt-get install -y nodejs 装的是 12.x，构建报引擎不匹配？
Ubuntu 22.04 仓库的 Node 过旧（apt policy nodejs 候选为 12.22.9）。按 4.2 用官方 tar.xz 装 v24；若已误装旧版，先 apt-get remove -y nodejs 再装。
Q2：npm ci 报依赖下载失败/超时？
npm 官方仓库访问受限时，临时换源 npm ci --registry=https://registry.npmmirror.com --no-audit --no-fund；仍失败则给构建机配代理后重试。本文实测环境为直连官方源成功。
Q3：浏览器打开房间链接刷新后 404？
Nginx 缺 SPA 回退。确认 location / 含 try_files $uri $uri/ /index.html，然后 nginx -t && systemctl reload nginx。
Q4：HTTPS 页面里摄像头/麦克风按钮无反应？
确认地址栏是 https:// 且无证书报错残留；WebRTC 媒体能力只在安全上下文可用。另外自建 tracker 若用 ws:// 会被浏览器按混合内容拦截，需改为 wss://。
Q5：/api/get-config 返回 {"error":"Not found"}？
访问路径不对（端点仅为 /api/get-config）或 API 进程未运行：systemctl is-active chitchatter-api，并用 journalctl -u chitchatter-api -n 50 看日志。
十一、卸载与清理
按组件逐个清理：
systemctl stop chitchatter-tracker
systemctl disable chitchatter-tracker
rm -f /etc/systemd/system/chitchatter-tracker.service
systemctl stop chitchatter-api
systemctl disable chitchatter-api
rm -f /etc/systemd/system/chitchatter-api.service
systemctl daemon-reload
rm -f /etc/nginx/sites-enabled/chitchatter
nginx -t && systemctl reload nginx
rm -rf /var/www/chitchatter /opt/chitchatter
rm -f /etc/ssl/certs/chitchatter.crt /etc/ssl/private/chitchatter.key
Node.js（如不再他用）：rm -rf /usr/local/{bin/node,bin/npm,bin/npx,lib/node_modules}。Nginx 本体按需 apt-get remove -y nginx。
十二、参考链接
- 源码仓库：https://github.com/jeremyckahn/chitchatter
- Node.js 官方下载：https://nodejs.org/dist/
- Nginx try_files 指令文档：https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files
- bittorrent-tracker（自建 tracker 实现）：https://github.com/webtorrent/bittorrent-tracker
本专栏其他篇目：《Chitchatter 介绍与选型指南》《Chitchatter Docker Compose 部署指南》《Chitchatter 配置参数详解》《Chitchatter 嵌入集成使用指南》。