Docker Compose

本指南用于通过单机 Docker Compose 部署包启动 Litefuse。部署包会在同一台机器上运行 Litefuse Web、Litefuse Worker、Postgres、Redis、MinIO 和 Doris。

前置要求

• Docker Engine、Docker Desktop 或 OrbStack
• Docker Compose v2
• 可用端口：3000, 3030, 5432, 16379, 19090, 19091, 8030, 9030, 9010, 8040, 8060, 9050, 9060

Apple Silicon 机器可能出现 linux/amd64 镜像平台提示，这是 Docker 的平台提示，不代表启动失败。

启动 Litefuse

进入自托管部署包目录后执行：

bash start.sh

如果从上一级目录执行：

cd litefuse && bash start.sh

首次运行时，如果 .env 不存在，脚本会自动创建 .env。生成的文件包含认证、加密、Postgres、Redis 和 MinIO 所需的密钥。

当前 Compose 使用 litefuse/litefuse-web:26.0.0 和 litefuse/litefuse-worker:26.0.0 镜像，并通过 platform: linux/amd64 运行。

打开应用

启动完成后访问：

http://localhost:3000

检查公开健康检查接口：

curl http://localhost:3000/api/public/health

正常返回示例：

{"status":"OK","version":"26.0.0"}

服务组件

默认 Docker 网络：

• litefuse_default: 10.200.0.0/24
• litefuse_doris_internal: 172.30.0.0/24

环境变量

如果要手动配置，先复制模板：

cp .env.example .env

然后编辑 .env，再启动 Litefuse：

bash start.sh

如果 .env 不存在，启动脚本会自动生成这些值：

• NEXTAUTH_SECRET
• SALT
• ENCRYPTION_KEY
• POSTGRES_PASSWORD
• REDIS_AUTH
• MINIO_ROOT_PASSWORD

应用容器使用 LITEFUSE_* 环境变量控制 Litefuse 特性：

• LITEFUSE_ENABLE_EXPERIMENTAL_FEATURES
• LITEFUSE_INIT_ORG_ID
• LITEFUSE_INIT_ORG_NAME
• LITEFUSE_INIT_PROJECT_ID
• LITEFUSE_INIT_PROJECT_NAME
• LITEFUSE_INIT_PROJECT_PUBLIC_KEY
• LITEFUSE_INIT_PROJECT_SECRET_KEY
• LITEFUSE_INIT_USER_EMAIL
• LITEFUSE_INIT_USER_NAME
• LITEFUSE_INIT_USER_PASSWORD
• LITEFUSE_ANALYTICS_BACKEND
• LITEFUSE_AUTO_DORIS_MIGRATION_DISABLED
• LITEFUSE_ENABLE_BACKGROUND_MIGRATIONS

Worker 默认启用 S3 batch export：

• LITEFUSE_S3_BATCH_EXPORT_ENABLED=true
• LITEFUSE_S3_BATCH_EXPORT_BUCKET=litefuse
• LITEFUSE_S3_BATCH_EXPORT_PREFIX=exports/
• LITEFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT=http://localhost:19090

Compose 中仍保留 ClickHouse 兼容环境变量，但当前部署使用 Doris 作为分析后端，因此 ClickHouse migration 已关闭。

常用命令

查看服务状态：

docker compose --env-file .env -f docker-compose.yml ps

查看日志：

docker compose --env-file .env -f docker-compose.yml logs -f

停止服务并保留持久化数据：

bash stop.sh

重新启动：

bash start.sh

删除容器、网络和所有数据卷：

docker compose --env-file .env -f docker-compose.yml down -v

down -v 会删除 Postgres、MinIO 和 Doris 的持久化数据，仅在确认不需要旧数据时使用。

升级

拉取镜像：

docker compose --env-file .env -f docker-compose.yml pull

重新启动 Litefuse：

bash start.sh

备份

备份 Postgres 元数据：

docker exec litefuse-postgres pg_dump -U postgres postgres > litefuse-postgres.sql

以下 Docker volumes 保存持久化数据：

• litefuse_postgres_data
• litefuse_minio_data
• litefuse_doris_fe_meta
• litefuse_doris_be_storage

常见问题

网络网段冲突

错误示例：

invalid pool request: Pool overlaps with other one on this address space

原因是本机已有 Docker 网络占用了 10.200.0.0/24 或 172.30.0.0/24。

查看网络：

docker network ls
docker network inspect <network-name> --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

如果旧网络可以删除：

docker network rm <network-name>

如果旧网络需要保留，请修改 docker-compose.yml 里的 networks.*.ipam.config.subnet 和 gateway。

容器名冲突

错误示例：

Conflict. The container name "/litefuse-doris" is already in use

查看占用容器：

docker ps -a --filter name='^/litefuse-doris$'

如果确认旧容器不需要：

docker rm -f litefuse-doris

Doris 启动慢或不健康

Doris 首次启动需要一段时间。查看日志：

docker logs --tail 200 litefuse-doris

如果看到代理相关报错，请确认宿主机或 Docker 运行环境没有向 Doris 容器注入 http_proxy、https_proxy 等代理环境变量。

Web 或 Worker 重启

查看日志：

docker logs --tail 200 litefuse-web
docker logs --tail 200 litefuse-worker

修改 .env 后请重建 Web 和 Worker：

docker compose --env-file .env -f docker-compose.yml up -d --force-recreate litefuse-web litefuse-worker