步骤 1：安装 Docker#

根据适用于你 Linux 发行版的 Docker 官方指南安装 Docker Engine：

• 安装 Docker Engine
• 安装 Compose 插件
• Linux 安装后续步骤

确认所安装的 Docker 版本：

1
docker --version
2
docker compose version

请使用 Docker Engine 24 或更高版本以及 Compose v2 插件。

步骤 2：下载技术栈#

创建一个工作目录并下载技术栈文件：

1
mkdir fluxer
2
cd fluxer
3

4
base=https://raw.githubusercontent.com/fluxerapp/fluxer/main/deploy/self-hosting
5
curl -fsSLO "$base/docker-compose.yml"
6
curl -fsSLO "$base/Caddyfile"
7
curl -fsSLO "$base/livekit.yaml"
8
curl -fsSL "$base/.env.example" -o .env

你现在应该包含以下文件：

1
Caddyfile
2
docker-compose.yml
3
livekit.yaml
4
.env

步骤 3：配置 .env#

在 .env 文件顶部设置公共主机名。 对于由 Caddy 直接获取证书的普通公共服务器：

1
FLUXER_DOMAIN=chat.example.com
2
FLUXER_PUBLIC_SCHEME=https
3
FLUXER_PUBLIC_PORT=443
4
FLUXER_CADDY_SITE_ADDRESS=chat.example.com
5
FLUXER_VAPID_EMAIL=admin@example.com

对于由 Cloudflare 终止 HTTPS 并将 HTTP 转发至 Caddy 的 Cloudflare Tunnel 配置：

1
FLUXER_DOMAIN=chat.example.com
2
FLUXER_PUBLIC_SCHEME=https
3
FLUXER_PUBLIC_PORT=443
4
FLUXER_CADDY_SITE_ADDRESS=:80
5
FLUXER_VAPID_EMAIL=admin@example.com

FLUXER_PUBLIC_SCHEME 和 FLUXER_PUBLIC_PORT 描述用户在浏览器中看到的协议与端口。FLUXER_CADDY_SITE_ADDRESS 描述 Caddy 在技术栈内部监听的地址。

生成所需的密钥：

1
for key in POSTGRES_PASSWORD MEILI_MASTER_KEY FLUXER_S3_SECRET_KEY \
2
  FLUXER_SUDO_MODE_SECRET FLUXER_CONNECTION_INITIATION_SECRET \
3
  FLUXER_GATEWAY_RPC_AUTH_TOKEN FLUXER_MEDIA_PROXY_SECRET_KEY \
4
  FLUXER_ADMIN_SECRET_KEY_BASE FLUXER_ADMIN_OAUTH_CLIENT_SECRET \
5
  LIVEKIT_API_SECRET; do
6
  sed -i "s|^$key=.*|$key=$(openssl rand -hex 32)|" .env
7
done
8

9
sed -i "s|^FLUXER_MEDIA_PROXY_UPLOAD_RELAY_SECRET_BASE64=.*|FLUXER_MEDIA_PROXY_UPLOAD_RELAY_SECRET_BASE64=$(openssl rand -base64 32)|" .env
10

11
VAPID=$(docker run --rm node:24-alpine npx --yes web-push generate-vapid-keys --json)
12
pub=$(printf '%s' "$VAPID" | grep -o '"publicKey":"[^"]*"' | cut -d'"' -f4)
13
priv=$(printf '%s' "$VAPID" | grep -o '"privateKey":"[^"]*"' | cut -d'"' -f4)
14
sed -i "s|^FLUXER_VAPID_PUBLIC_KEY=.*|FLUXER_VAPID_PUBLIC_KEY=$pub|" .env
15
sed -i "s|^FLUXER_VAPID_PRIVATE_KEY=.*|FLUXER_VAPID_PRIVATE_KEY=$priv|" .env

除非明确知道需要修改，否则请保持以下默认设置：

• LIVEKIT_API_KEY=fluxer；密钥为 LIVEKIT_API_SECRET。
• FLUXER_S3_ACCESS_KEY=fluxer；密钥为 FLUXER_S3_SECRET_KEY。
• 电子邮件功能初始状态为禁用。后续可通过 .env 和管理员仪表盘启用 SMTP。

步骤 4：发布主机名#

为主机名创建 DNS 记录：

• 从 chat.example.com 指向服务器 IPv4 地址的 A 记录。
• （可选）从 chat.example.com 指向服务器 IPv6 地址的 AAAA 记录。 保持 FLUXER_CADDY_SITE_ADDRESS=chat.example.com。当端口 80/tcp 和 443/tcp 可以访问服务器时，Caddy 将自动申请并续订证书。

步骤 5：开放防火墙#

如果你使用的是直接暴露在公网上的服务器，请允许以下入站流量：

• 22/tcp 或你的 SSH 端口。
• 用于 Caddy 的 80/tcp 和 443/tcp。
• 用于 LiveKit 媒体的 7881/tcp 和 7882/udp。 如果你对 Web 流量使用了 Cloudflare Tunnel，可以在云服务商的防火墙处拦截入站的 80/tcp 和 443/tcp。同时保持 LiveKit 媒体端口关闭，除非你意图开放语音/视频媒体或正在使用 TURN 服务器。

步骤 6：启动技术栈#

启动 Fluxer：

1
docker compose up -d

如果你使用了上述的 Cloudflare 覆盖配置，请同时启动这两个文件：

1
docker compose -f docker-compose.yml -f cloudflared.compose.yml up -d

观察启动状态：

1
docker compose ps
2
docker compose logs -f api

首次启动可能需要几分钟时间，因为需要下载镜像并初始化服务。seaweedfs-init 在创建对象存储桶后会退出，这是正常现象。

步骤 7：验证实例#

在 Shell 中设置你的域名：

1
export FLUXER_DOMAIN=chat.example.com

检查每一个公共 HTTP 入口点：

1
for path in /_health /api/_health /gateway/_health /media/_health /admin/_health; do
2
  curl -fsS -o /tmp/fluxer-check -w "$path %{http_code}\n" "https://$FLUXER_DOMAIN$path"
3
done

预期结果：

1
/_health 200
2
/api/_health 200
3
/gateway/_health 200
4
/media/_health 200
5
/admin/_health 200

检查实例发现（instance discovery）：

1
curl -fsS "https://$FLUXER_DOMAIN/api/.well-known/fluxer" | jq '.features.self_hosted, .endpoints.admin, .endpoints.gateway, .endpoints.media, .endpoints.static_cdn'

你应该看到 true、以 /admin 结尾的管理员 URL、以 /gateway 结尾的网关 URL、以 /media 结尾的媒体 URL，以及与实例源（origin）相同的静态资源 URL。 检查 Web 应用、管理员登录页面、应用包以及静态资源容器：

1
curl -fsSI "https://$FLUXER_DOMAIN" | sed -n '1,8p'
2
curl -fsSI "https://$FLUXER_DOMAIN/admin/login" | sed -n '1,8p'
3

4
asset=$(curl -fsS "https://$FLUXER_DOMAIN" | grep -o 'src="[^"]*/assets/[^"]*"' | head -n1 | cut -d'"' -f2)
5
case "$asset" in
6
  http*) curl -fsSI "$asset" | sed -n '1,8p' ;;
7
  /*) curl -fsSI "https://$FLUXER_DOMAIN$asset" | sed -n '1,8p' ;;
8
esac
9

10
curl -fsSI "https://$FLUXER_DOMAIN/fonts/ibm-plex.css?v=3" | sed -n '1,8p'
11
curl -fsSI "https://$FLUXER_DOMAIN/web/favicon-32x32.png" | sed -n '1,8p'

如果你使用了 Cloudflare Tunnel 并遇到了 HTTP 530 错误，这说明 Tunnel 连接器当前未建立连接，或者公共主机名路由指向了错误的服务。

步骤 8：创建所有者账户#

打开 Web 应用：

1
https://chat.example.com

注册第一个账户。在自托管实例上，第一个被接受注册的账户将获得通配符管理员权限（wildcard admin access）。使用该账户进行首次管理员登录：

1
https://chat.example.com/admin

在管理员仪表盘中完成初始设置。至少需要审查以下内容：

• 品牌标识与实例名称。
• 注册模式：开放、审核或关闭。
• 电子邮件发送。
• 验证码策略（如果你开放了公共注册）。
• 单一社区模式（如果你希望使用一个默认社区，而非由用户创建多个社区）。
• 语音区域与 LiveKit 可达性（如果你启用了语音功能）。

电子邮件#

电子邮件默认处于禁用状态。要启用 SMTP，请在 .env 中设置以下变量，并重启 api、worker 和 admin 服务：

1
FLUXER_EMAIL_ENABLED=true
2
FLUXER_EMAIL_PROVIDER=smtp
3
FLUXER_EMAIL_FROM_EMAIL=noreply@example.com
4
FLUXER_EMAIL_FROM_NAME=Fluxer
5
FLUXER_EMAIL_SMTP_HOST=smtp.example.com
6
FLUXER_EMAIL_SMTP_PORT=587
7
FLUXER_EMAIL_SMTP_USERNAME=example
8
FLUXER_EMAIL_SMTP_PASSWORD=example-secret
9
FLUXER_EMAIL_SMTP_SECURE=true

随后在 /admin/instance-config 页面测试 SMTP 配置。

语音与视频#

Fluxer 使用 LiveKit 处理语音和视频。Caddy 将 /livekit 路由至 LiveKit 的 HTTP/WebSocket 信令端口，但浏览器的媒体流通过 WebRTC 传输：

• 7882/udp 是正常的媒体路径。
• 7881/tcp 是 TCP 回退路径。
• 7880/tcp 保持私有，位于 Caddy 后端用于信令传输。 在开放了 7881/tc 和 7882/udp 的 VPS 上，LiveKit 通常可以自动检测公网 IP。在 NAT、Cloudflare Tunnel 或受限网络环境下，请添加 TURN 服务器并为其配置 LiveKit。

备份#

在升级前和定期计划中备份以下项目：

• .env
• postgres-data
• seaweedfs-data

如需进行冷备份：

1
docker compose stop api worker gateway admin app-proxy media-proxy static-proxy livekit
2
docker run --rm -v fluxer_postgres-data:/data -v "$PWD/backups:/backup" alpine tar czf /backup/postgres-data.tgz -C /data .
3
docker run --rm -v fluxer_seaweedfs-data:/data -v "$PWD/backups:/backup" alpine tar czf /backup/seaweedfs-data.tgz -C /data .
4
docker compose up -d

对于生产环境，优先使用 Postgres 原生转储（dump）加上对象存储备份，这样无需停止实例运行。

升级#

默认的镜像标签为 v1，它会跟踪最新的兼容版本：

1
docker compose pull
2
docker compose up -d

fluxer-static 镜像属于默认技术栈的一部分，因此静态资源的更新会通过相同的拉取和重启流程同步完成。 要锁定特定版本，请将 .env 中的 FLUXER_IMAGE_TAG 设置为你希望使用的版本标签，然后执行拉取并重启。