Huly 0.7.426 Docker Compose 部署实战

目标：在一台 Linux 服务器上，从零完成 Huly（hcengineering/platform，官网 huly.io）官方 selfhost 形态的 Docker Compose 部署：获取官方部署物 → 生成配置 → 编排启动 14 个服务 → 初始化账号与工作区 → 功能验证，并沉淀本次实测中真实发生的四类故障排查记录（消息队列与搜索引擎存储目录权限、健康检查探针 SASL 状态不匹配、全文检索服务 DNS 收敛）。Huly 的产品定位、架构与选型对比见本专栏《Huly 介绍与选型指南》，配置项逐项说明见《Huly 配置参数详解》，日常运维命令见《Huly 常用 CLI 命令与运维实战》。

一、环境信息

本次部署在独立实验服务器上完成，全过程数据如下：

版本取证的官方依据：huly-selfhost 仓库 README 明确「自托管部署请使用生产版本（v* 标签）」，setup.sh 生成的配置中 HULY_VERSION=v0.7.426、桌面更新通道 DESKTOP_CHANNEL=0.7.426（实查于 2026-10-27）。

资源要求方面，官方 selfhost README 给出了明确数字：最低 2 vCPU / 8 GB 内存，推荐 4 vCPU / 16 GB 以上，并警告低于最低配置的服务器可能出现无响应或失败。本次实测整栈稳态内存占用约 4.7 GiB（各服务实测值见第五节），加上系统余量，8 GB 内存是实际可跑的底线。

二、认识官方 selfhost 部署物

Huly 官方自托管通道是 GitHub 上的 hcengineering/huly-selfhost 仓库（Compose 与 Kubernetes 配置都在这个仓库，平台源码仓库 hcengineering/platform 只提供应用本身）。仓库结构如下：

huly-selfhost/
├── setup.sh              # 交互式配置生成脚本（生成 huly_v7.conf 与 nginx 配置）
├── compose.yml           # Docker Compose 编排文件（14 个服务）
├── run-tool.sh           # 管理工具入口（运行 hardcoreeng/tool）
├── nginx.conf / nginx.sh # 反向代理配置与启用 SSL 的辅助脚本
├── traefik/              # Traefik 反代形态的配置样例
├── guides/               # SMTP 邮件配置、Gmail 集成排障指南
├── kube/                 # Kubernetes 原生 manifests（14 个服务的 Deployment/Service 等）
├── helm/                 # Helm chart（chart 版本 0.1.0，appVersion 0.7.426）
├── MIGRATION.md          # 版本升级迁移说明（0.6.x → 0.7.x 必读）
└── backup-create.sh / restore-workspace.sh 等

2.1 服务拓扑与依赖链

compose.yml 编排了 14 个服务，这是理解 Huly 部署复杂度的关键。按职能分组：

💡 技术拓展：Huly 的持久化组合是「CockroachDB（分布式 SQL，兼容 PostgreSQL 线协议）+ MinIO 兼容对象存储 + Elasticsearch 7 + Redpanda（Kafka 兼容队列）」。同类一体化项目管理平台中，Plane 用 PostgreSQL + Redis + RabbitMQ，OpenProject 用 PostgreSQL，Redmine 用单一关系库——Huly 的存储层拆分最重，这是它功能面（实时协同 + 全文搜索 + 事件驱动）换来的代价，也是部署篇必须逐服务起停验证的原因。

两点值得注意的官方编排细节：

1. 对象存储用的是 pgsty/silo 而非 minio/minio 镜像。MinIO 官方镜像 2025 年起变更了开源许可策略，社区衍生镜像成为常见替代；编排中访问凭据固定为 minioadmin/minioadmin（内网服务间访问）。
2. mongodb、redis、hulypulse 三个服务在官方编排中处于注释状态，仅 AI 助手（aibot）、日历、推送通知（HulyPulse）功能需要，按需启用。

三、前置准备

3.1 获取官方部署物

# 实测：克隆官方 selfhost 仓库
git clone --depth 1 https://github.com/hcengineering/huly-selfhost.git
cd huly-selfhost

⚠️ 网络说明：2026-10-27 实测环境直连 GitHub 出现 Connection reset by peer，走代理后克隆成功（git -c http.proxy=http://192.168.1.62:7897 clone ...）。网络受限环境请按「官方源 → 国内镜像加速 → 代理」降级链处理，当前实测可用渠道为代理直连 GitHub。

克隆完成后先看两个文件：compose.yml（编排事实，第二节已解读）和 setup.sh（配置生成器）。setup.sh 支持的参数：

$ ./setup.sh --help
Usage: setup.sh [OPTIONS]
Options:
  --secret         Generate a new secret key
  --reset-volumes  Reset all volume paths to default Docker named volumes
  --quick          Quick setup with defaults (localhost:8087, no SSL, auto-start)
  --help           Show this help message

💡 技术拓展：--quick 是官方提供的最小交互路径（默认 localhost:8087、无 SSL、自动启动），适合本机体验；生产部署建议走交互模式，把 HOST_ADDRESS 设为真实域名或服务器 IP。两种路径生成的配置文件格式完全一致，差异只在变量取值。

3.2 端口与网络规划

本实验环境按以下原则规划（多套服务共存的宿主机上必须显式规划，避免冲突）：

• 入口端口：从空闲段选定 8138（ss -ltn 确认未被占用）；
• 编排网络子网：检查宿主机已占用的 Docker 网段后，显式指定 10.89.61.0/24（docker network ls + 已建网络网段核对，避开默认池与 192.168.x/100.64.x 段）；
• 数据卷：官方 compose 支持两种持久化方式——不设 VOLUME_*_PATH 时用 Docker 命名卷；生产/实验均建议显式 bind mount 到固定目录，便于备份与清理。本次实测将五个数据目录统一放在部署工作目录旁的 volumes/ 下。

四、配置初始化

4.1 运行 setup.sh 生成配置

在仓库根目录执行（交互模式）：

$ ./setup.sh
Config file "huly_v7.conf" not found. Let's create one!
...

脚本会依次询问接入地址、是否启用 SSL、端口、数据卷路径等，全部选项写入 huly_v7.conf。本次实测生成的配置全文如下（机密已脱敏为节选，结构与实测一致）：

HULY_VERSION=v0.7.426
DESKTOP_CHANNEL=0.7.426
DOCKER_NAME=huly-0.7.426-stack

# The address of the host or server from which you will access your Huly instance.
HOST_ADDRESS=localhost:8138

# Set this variable to 'true' to enable SSL (HTTPS/WSS). 
# Leave it empty to use non-SSL (HTTP/WS).
SECURE=

# Specify the IP address to bind to; leave blank to bind to all interfaces (0.0.0.0).
HTTP_PORT=8138
HTTP_BIND=

# Huly specific variables
TITLE=Huly
DEFAULT_LANGUAGE=en
LAST_NAME_FIRST=true

# CockroachDB variables
CR_DATABASE=defaultdb
CR_USERNAME=selfhost
CR_USER_PASSWORD=<setup.sh 自动生成的 64 位十六进制串>
CR_DB_URL=postgres://selfhost:<同上密码>@cockroach:26257/defaultdb

# Redpanda variables
REDPANDA_ADMIN_USER=superadmin
REDPANDA_ADMIN_PWD=<setup.sh 自动生成的 64 位十六进制串>

# Docker volume paths - specify custom paths for persistent data storage
VOLUME_ELASTIC_PATH=/opt/data/quzuo/tmp/huly/volumes/elastic
VOLUME_FILES_PATH=/opt/data/quzuo/tmp/huly/volumes/files
VOLUME_CR_DATA_PATH=/opt/data/quzuo/tmp/huly/volumes/cr_data
VOLUME_CR_CERTS_PATH=/opt/data/quzuo/tmp/huly/volumes/cr_certs
VOLUME_REDPANDA_PATH=/opt/data/quzuo/tmp/huly/volumes/redpanda

# Run with --secret to regenerate.
SECRET=<setup.sh 自动生成的 64 位十六进制串>

变量逐项含义与修改方法见《Huly 配置参数详解》，本节只强调三个部署期关键项：

1. DOCKER_NAME 决定 Compose 项目名与所有服务实例的默认命名前缀，本项目为 huly-0.7.426-stack；
2. HOST_ADDRESS 必须与用户实际访问地址一致（SECURE 为空时是 主机:端口 形态），account/front 等服务会用它拼回调地址，配错会导致登录页能开但注册/登录失败；
3. 数据卷五件套路径按 3.2 节规划显式落盘。

4.2 对接 compose 与网络子网

compose 默认读取同目录 .env 文件，把生成的配置软链过去：

$ ln -s huly_v7.conf .env
$ ls -la .env
lrwxrwxrwx 1 root root 12 Oct 27 19:27 .env -> huly_v7.conf

官方 compose.yml 末尾的网络段默认写死了一个子网，多套编排共存时需要改成自己规划的槽位：

networks:
  huly_net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

五、编排启动与启动顺序

5.1 首次启动

$ docker compose up -d
[+] Running 15/15
 ✔ Network huly-0.7.426-stack_huly_net  Created
 ✔ Container huly-0.7.426-stack-stats-1       Started
 ✔ Container huly-0.7.426-stack-kvs-1         Started
 ✔ Container huly-0.7.426-stack-minio-1       Started
 ...（14 个服务全部 Started）

说明：Compose 服务实例的命名规则是「项目名-服务名-1」（如 huly-0.7.426-stack-transactor-1），下文排障章节按服务名指代。

首次启动会拉取 14 个服务的程序包，官方仓库拉取较慢，必要时走代理：

docker compose pull

5.2 启动状态核对

$ docker compose ps
SERVICE        STATUS
account        Up 30 minutes
cockroach      Up 30 minutes
collaborator   Up 30 minutes
elastic        Up 14 minutes (healthy)
front          Up 30 minutes
fulltext       Up 4 minutes
kvs            Up 30 minutes
minio          Up 30 minutes (healthy)
nginx          Up 30 minutes
redpanda       Up 14 minutes (unhealthy)
rekoni         Up 30 minutes
stats          Up 30 minutes
transactor     Up 30 minutes
workspace      Up 30 minutes

14 个服务全部 Up 即启动完成。elastic 显示 healthy、redpanda 显示 unhealthy 的原因在第九节排障实录第 3 条——这是官方编排探针配置与镜像默认模式不匹配的已知形态，功能不受影响，判断队列健康的依据是下游服务（transactor/account/fulltext）能否正常收发事件。

5.3 整栈资源占用实测

启动完成并初始化一个工作区后，整栈稳态资源占用如下（docker stats --no-stream 汇总）：

结论印证了官方「资源较重」的定位：内存大头是 redpanda（2 GB）与 Elasticsearch（Java 堆固定 1 GB，编排中 ES_JAVA_OPTS=-Xms1024m -Xmx1024m）。8 GB 内存的服务器跑整栈 + 系统，余量已很薄；生产建议 16 GB 起步。

六、初始化：账号与工作区

Huly 的初始化分两步：创建用户账号（主库 global_account）与创建工作区（工作区独立事务库）。两条路径：Web 注册（产品常规路径）与管理 CLI（自动化/无邮件场景）。本节以实测的 CLI 路径为主线。

6.1 用管理工具创建账号

官方仓库的 run-tool.sh 封装了管理工具（同版本 hardcoreeng/tool，命令清单与用法详见《Huly 常用 CLI 命令与运维实战》）。创建账号：

$ ./run-tool.sh create-account root@huly.local -p q1w2e3r4 -f Root -l Admin
creating account Root Admin (root@huly.local)...

无报错即创建成功。账号写入主库的 person 与 social_id 表（social_id.value 即登录邮箱）：

$ # 服务端核对（数据库侧验证）
SELECT * FROM global_account.social_id WHERE value LIKE '%root@%';
type    value             key                    person_uuid                          created_on     verified_on    _id                is_deleted  display_value
email   root@huly.local   email:root@huly.local  5ea0f331-f8bc-49ba-8b0c-28668f021b02 1793106270129  1793106270128  1222363939853107201 f          NULL

两个要点：

1. create-account 直接落库且 verified_on 已有值，跳过了 Web 注册的邮箱验证码环节——selfhost 未配置 SMTP 时，这是最顺畅的初始化方式（SMTP 配置见《Huly 配置参数详解》）；
2. 若邮箱已存在会显式报错 PlatformError: ERROR: platform:status:AccountAlreadyExists，不会静默覆盖。

说明：Huly 的账号名是邮箱形态，本专栏统一用 root@huly.local（密码 q1w2e3r4，实测满足 Huly 密码策略）与 admin@huly.local 两个演示账号。

6.2 创建工作区并分配成员

$ ./run-tool.sh create-workspace demo "email:root@huly.local"
...（工作区初始化日志）
$ ./run-tool.sh assign-workspace root@huly.local demo
assigning user root@huly.local to demo...

create-workspace 的第二个参数是所有者的 social id（email:<邮箱> 格式）。完成后主库 workspace 表出现新工作区：

name      data_id  created_by
demo      NULL     5ea0f331-f8bc-49ba-8b0c-28668f021b02
devteam   NULL     398d66a5-24d2-4146-901c-3c80e80964db

每个工作区在数据库中是一套独立 schema（工作区事务库 tx/model_tx/space/documents 等表），create-workspace 会同步完成模型初始化，之后该工作区即可登录使用。

6.3 Web 端登录与日常建项目/建任务

浏览器访问 http://<HOST_ADDRESS>（本次实测 http://localhost:8138），以 6.1/6.2 创建的账号登录、选择工作区，进入工作台后即可按产品常规路径使用：左侧 Tracker 建项目（填写项目名与标识前缀），项目内创建 issue 并指派、排期；Docs 建文档；Chat 建频道。Web 注册新用户走「Sign up → 邮箱验证码 → 创建/加入工作区」流程，验证码依赖 SMTP（未配置 SMTP 时用 6.1 的 CLI 方式替代）。

页面可达性验证：

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8138/
200

七、功能验证

部署是否真正可用，验证三层链路：

① 接入层：入口 200（见 6.3）。

② 全文检索链路（transactor → redpanda 队列 → fulltext → elastic）：工作区初始化后，如果数据产生早于 elastic 就绪（或发生过第九节的队列故障），需要手动触发重建索引：

$ RUN_TOOL_DOCKER_ARGS="-e FULLTEXT_URL=http://fulltext:4700" ./run-tool.sh fulltext-reindex demo
done demo

随后在搜索引擎侧核对索引文档数（实测量化）：

$ curl -s 'http://<elastic 内网地址>:9200/_cat/indices/huly_storage_index_v2?v&h=index,docs.count,store.size'
index                  docs.count store.size
huly_storage_index_v2         96    102.6kb

索引从 0 增长到 96 条文档、102.6 kb，全文检索链路贯通。

③ 数据持久层：主库 global_account 与工作区事务库均有数据落盘（6.1/6.2 的查询回显即证据），对象存储的 files 卷在附件上传后增长。

八、k8s 部署形态（附）

本节为部署形态溯源说明（来源：hcengineering/huly-selfhost 仓库 kube/ 与 helm/ 目录，实查于 2026-10-27），本批未做 k8s 集群实测；Huly 属于 Tier2 社区/官方仓库自带形态，k8s 集群级部署实测将在后续 k8s 专项批次进行。

官方 selfhost 仓库自带两套 k8s 形态，与 Compose 编排同源：

1. 原生 manifests（kube/）：14 个服务各自独立目录（account/cockroach/collaborator/elastic/front/fulltext/minio/redpanda/rekoni/stats/transactor/workspace/config），附 QUICKSTART.md 提供 kind 快速上手（kind 集群 + extraPortMappings 把 80 端口映射到宿主机）。适合想逐层控制 Yaml 的运维。
2. Helm chart（helm/huly）：chart version: 0.1.0、appVersion: "0.7.426"（与本次 Compose 实测同版本），templates/ + values.yaml 标准结构，适合参数化批量部署。

选择建议：生产 k8s 部署优先 Helm chart 形态（版本随 appVersion 锚定，升级走 helm upgrade）；学习/验证用 manifests 逐个起服务更直观。两种形态的存储层（CockroachDB/ES/Redpanda/MinIO）在 k8s 中的持久化与资源配置，将在 k8s 专项实测后补充。

九、排障实录（真实故障沉淀）

本次部署实测共踩到四类故障，全部有日志佐证，逐条沉淀如下。

9.1 消息队列启动失败：数据目录 Permission denied

现象：首次 docker compose up -d 后，redpanda 服务反复退出（Exited (1)），日志尾部：

ERROR 2026-10-27 12:33:56,878 [shard 0:main] main - application.cc:527 - Failure during startup: std::__1::system_error (error system:13, open: Permission denied)

根因：redpanda 程序在数据目录中写 pid.lock 等文件时被拒。官方镜像内以非 root 专用用户（uid=101，redpanda:redpanda）运行，而 VOLUME_REDPANDA_PATH 指向的宿主机目录是 root:root 属主（0755），专用用户无写权限。这是bind mount 场景特有的问题——用 Docker 命名卷时引擎会自动按镜像内用户初始化属主，显式 bind mount 则完全沿用宿主机属主。

修复：

# 实测确认镜像内运行用户后修正属主
$ docker run --rm --entrypoint id docker.io/redpandadata/redpanda:v24.3.6 redpanda
uid=101(redpanda) gid=101(redpanda) groups=101(redpanda)
$ chown -R 101:101 volumes/redpanda
$ docker compose restart redpanda

9.2 搜索引擎启动失败：数据目录无法创建

现象：elastic 服务重启循环，日志为 Java 堆栈：

java.nio.file.AccessDeniedException: /usr/share/elasticsearch/data/nodes
  at java.nio.file.UnixFileSystemProvider.newByteChannel(...)
  at org.elasticsearch.env.NodeEnvironment.<init>(NodeEnvironment.java:262)
  ...

根因：与 9.1 同源。官方 elasticsearch 镜像以 uid=1000（elasticsearch 用户）运行，bind mount 的 volumes/elastic 属主是 root。

修复：

$ chown -R 1000:1000 volumes/elastic
$ docker compose restart elastic
...（随后 docker compose ps 显示 elastic Up (healthy)）

经验：官方编排改为 bind mount 后，每个有状态服务启动前都要核对「镜像内运行 uid ↔ 宿主机目录属主」。本次 14 个服务中仅这两个中招（minio/cockroach 的镜像以 root 或初始化流程自行处理），修复后整栈稳定。

9.3 队列健康检查显示 unhealthy：探针与认证模式不匹配

现象：redpanda 修复启动后 docker compose ps 一直显示 unhealthy，但下游服务事件收发正常。手动执行官方探针命令复现：

$ rpk cluster info -X user=superadmin -X pass=<REDPANDA_ADMIN_PWD>
unable to request metadata: ILLEGAL_SASL_STATE: Request is not valid given the current SASL state.

根因：官方编排给 redpanda 配置了 --mode dev-container（开发容器模式，未启用 SASL 认证），但 healthcheck 探针却带 REDPANDA_SUPERUSER_USERNAME/PASSWORD 凭据以 SASL 方式连接，broker 对未启用认证的连接返回 ILLEGAL_SASL_STATE，探针必然失败。

处置：这是官方编排的探针配置与镜像模式不匹配，不影响功能，不引入偏离官方编排的修改。判断队列是否健康的实用依据是下游消费服务状态（见 9.4）与 transactor/account 日志中无队列连接错误。

9.4 全文检索无索引：队列消费方 DNS 收敛失败

现象：工作区数据已产生，但 ES 索引 huly_storage_index_v2 文档数为 0。fulltext 服务日志持续报错：

KafkaJSNumberOfRetriesExceeded: Connection error: getaddrinfo EAI_AGAIN redpanda
    at Socket.onError (/usr/src/app/bundle.js:151056:28)
{"level":"info","message":"workspace event",...,"type":"full-fulltext-reindex",...}

根因链：① redpanda 因 9.1 修复而重启，服务实例换了内网 IP；② fulltext 进程内的 DNS 解析（glibc getaddrinfo）在实例 IP 变更后持续 EAI_AGAIN，消费循环反复失败且把队列消息标记为已处理；③ 即使 9.1/9.2 修复后 getent hosts redpanda 在同网络其他服务里正常解析，fulltext 的既有进程也无法自愈。

修复：

$ docker compose restart fulltext
...（重启后日志：[ConsumerGroup] Consumer has joined the group, groupId: tx-fulltext / workspace-fulltext / fulltext-fulltext）

三个消费组全部重新入组后，再补触发一次重建索引（见第七节），索引文档数从 0 → 96，链路恢复。

经验：强依赖队列/数据库的有状态应用，在依赖方重启后自身也要重启，这是 Compose 场景下「重启顺序」的实战补充——官方编排未对 fulltext 配置 depends_on 条件等待，依赖恢复后手动重启消费方是最稳妥的收敛方式。

十、部署收尾与数据留存

日常启停与备份属于运维范畴，命令矩阵见《Huly 常用 CLI 命令与运维实战》。部署实验结束时的清理动作（按需）：

$ docker compose down            # 停止并移除编排（保留数据卷）
$ docker compose down -v         # 连同命名卷一并删除（bind mount 目录需手动清理）

本次实测的五处 bind mount 数据目录（elastic/files/cr_data/cr_certs/redpanda）在 volumes/ 下，整体打包即可留存实验数据；恢复部署时放回原路径、修正 9.1/9.2 的目录属主即可无缝续跑。

延伸阅读

• 《Huly 介绍与选型指南》：产品定位、架构与 Linear/Plane/OpenProject 量化对比
• 《Huly 配置参数详解》：huly_v7.conf 与服务级环境变量逐项说明、SMTP/SSL 配置
• 《Huly 常用 CLI 命令与运维实战》：管理工具命令清单、备份恢复、账户与索引运维矩阵