Huly 配置参数详解

Huly selfhost 配置体系逐项详解（v0.7.426 实测）：huly_v7.conf 七组顶层变量、14 个服务环境变量职责与内网依赖串、账号初始化双路径（Web 注册 vs 管理 CLI）、SMTP/SSL/默认内容/对象存储凭据实操与配置变更生效路径速查，含配置视角排障实录（2026-10-27）。

HulyHuly项目管理2026/10/27

Huly 配置参数详解

目标：逐项讲清 Huly selfhost 部署的完整配置体系——顶层配置文件 huly_v7.conf 的每个变量、Compose 编排中 14 个服务的环境变量职责、以及账号初始化（Web 注册与管理 CLI）两种机制，并给出 SMTP 邮件、SSL、禁用工作区默认内容等高频配置场景的实操步骤与配置视角的排障实录。部署过程本身见《Huly 0.7.426 Docker Compose 部署实战》，日常运维命令见《Huly 常用 CLI 命令与运维实战》。本文全部配置与命令在 v0.7.426 实例上实测（2026-10-27）。

一、环境信息与配置体系总览

项目值
Huly 版本v0.7.426
部署形态官方 huly-selfhost 仓库 + Docker Compose
配置文件huly_v7.conf（setup.sh 生成，软链为 .env 供 compose 读取）
实测日期2026-10-27

Huly 的配置分三层，改动前先判断目标参数在哪一层：

层载体管什么典型例子
顶层huly_v7.conf版本、接入地址、数据库/队列凭据、数据卷路径、密钥HULY_VERSION、HOST_ADDRESS、CR_DB_URL
服务级compose.yml 各服务的 environment服务间地址、功能开关、语言与品牌ACCOUNTS_URL、MODEL_ENABLED、DISABLED_FEATURES
存储内置各存储服务自身数据库/搜索引擎/队列/对象存储的内部参数CockroachDB --accept-sql-without-tls、Elasticsearch ES_JAVA_OPTS

理解三层分工的关键：compose 编排通过 ${变量} 把顶层 conf 的值注入各服务环境变量（如 DB_URL=${CR_DB_URL}），所以改顶层 conf 后重启服务即生效；而服务级 environment 里写死的值需要编辑 compose.yml 本身。

二、顶层配置 huly_v7.conf 逐项详解

setup.sh 交互生成的 huly_v7.conf 共七组变量。以下按组逐项说明（值取自本次实测实例，机密项脱敏）。

2.1 版本与编排项目名

变量实测值说明
HULY_VERSIONv0.7.426平台版本标签，决定全部 hardcoreeng 服务程序的版本；取值参考官方 GitHub Releases 的 v* 生产标签
DESKTOP_CHANNEL0.7.426桌面客户端更新通道，与 HULY_VERSION 去掉 v 前缀保持一致
DOCKER_NAMEhuly-0.7.426-stackCompose 项目名，同时决定各服务实例的默认命名前缀；同一宿主机跑多套 Huly 时必须改它防互串

版本升级注意：官方要求升级前先读 MIGRATION.md 找到目标版本的迁移说明；从 0.6.x 升 0.7.x 必须走专门的迁移流程（尤其 v0.7.204 的分步迁移），不能原地直接改版本号拉起。升级动作本身：改 HULY_VERSION/DESKTOP_CHANNEL → docker compose pull → docker compose up -d。

2.2 接入地址与 SSL

变量实测值说明
HOST_ADDRESSlocalhost:8138实例对外访问地址（域名或 IP:端口）。生产必须设为用户真实访问入口：account/front 等服务用它拼接注册回调、登录跳转等绝对地址，配错是「页面能开但注册/登录失败」的头号原因
SECURE（空）是否启用 HTTPS/WSS。留空为 HTTP；设为 true 后服务间拼地址自动切换 https/wss 前缀（编排里的 ${SECURE:+s} 技巧）
HTTP_PORT8138入口监听端口（nginx 对外暴露）
HTTP_BIND（空）绑定 IP，留空绑全部网卡；只允许内网访问时填内网 IP

SECURE/HTTP_PORT/HTTP_BIND/HOST_ADDRESS 任何一项变更后，必须重新生成 nginx 反代配置（仓库内 ./nginx.sh，只覆盖必要段落、保留自定义 SSL 配置）再重启服务，否则入口转发与实际端口/协议脱节。

2.3 产品级选项

变量实测值说明
TITLEHuly站点标题（front 服务 TITLE 变量注入，浏览器标签页显示，可品牌化）
DEFAULT_LANGUAGEen界面默认语言；front 服务同名变量注入（可设 zh 等）
LAST_NAME_FIRSTtrue姓名显示顺序（姓在前）。transactor 与 front 均注入该值

2.4 CockroachDB（主数据库）

变量实测值说明
CR_DATABASEdefaultdb业务库名。注意：主库 global_account schema 与各工作区事务库都在这一个库里（schema 级隔离）
CR_USERNAME / CR_USER_PASSWORDselfhost / 自动生成业务连接账号与密码（setup.sh 生成 64 位十六进制）
CR_DB_URLpostgres://selfhost:<密码>@cockroach:26257/defaultdb完整连接串，transactor/account/workspace/kvs 等服务共享注入；CockroachDB 兼容 PostgreSQL 线协议，故 URL 是 postgres scheme

管理操作连接示例（实测可用；密码即 CR_USER_PASSWORD）：

$ echo "SHOW DATABASES;" | ./cockroach sql --url "postgres://selfhost@localhost:26257/defaultdb?sslmode=disable"
  database_name
  defaultdb
  postgres
  system

提醒：官方 README 明确说明自托管编排中的 CockroachDB 是单节点 start-single-node 形态，生产使用前应对照官方生产设置文档评估。

2.5 Redpanda（消息队列）

变量实测值说明
REDPANDA_ADMIN_USERsuperadmin队列超管账号（compose 健康探针引用它；详见部署篇排障实录——探针与 dev-container 模式不匹配时显示 unhealthy，功能不受影响）
REDPANDA_ADMIN_PWD自动生成队列超管密码

应用服务连接队列用的是内网地址 redpanda:9092（各服务 QUEUE_CONFIG），不走 SASL。

2.6 数据卷路径

变量实测值说明
VOLUME_ELASTIC_PATH绝对路径全文索引数据
VOLUME_FILES_PATH绝对路径用户上传文件与附件（对象存储数据）
VOLUME_CR_DATA_PATH绝对路径数据库数据
VOLUME_CR_CERTS_PATH绝对路径数据库证书目录
VOLUME_REDPANDA_PATH绝对路径队列数据

五项留空则回退 Docker 命名卷；./setup.sh --reset-volumes 可一键全部复位为命名卷。自定义路径必须匹配服务内运行用户的 uid 属主——官方 README 原文提醒 chown -R 1000:1000 /var/huly/db（多数服务用 1000），但 redpanda 用 uid 101。本次实测正是踩了这两处（见第六节排障实录一、二）。

2.7 SECRET（服务间签名密钥）

变量说明
SECRET全平台共享的签名密钥，注入各应用服务的 SERVER_SECRET，用于 JWT 签发校验与服务间信任。./setup.sh --secret 可重新生成；更换后所有已签发令牌失效，用户需重新登录

三、服务级环境变量详解

compose.yml 中 14 个服务的 environment 是第二层配置。顶层 conf 注入之外，服务间还有一组内网服务发现地址，逐项列表如下（均为实测编排事实）。

3.1 应用服务公共变量

变量出现的服务取值说明
SERVER_SECRETtransactor/account/workspace/front/collaborator/fulltext/rekoni${SECRET}签名密钥（顶层 SECRET 注入）
SERVER_PORTtransactor/account/front3333/3000/8080各服务监听端口
DB_URLtransactor/account/workspace${CR_DB_URL}主库连接串
ACCOUNTS_DB_URLworkspace${CR_DB_URL}账号库连接（与主库同库）
STORAGE_CONFIG全部有存储需求的服务`miniominio?accessKey=minioadmin&secretKey=minioadmin`
QUEUE_CONFIGtransactor/account/workspace/fulltextredpanda:9092队列地址（事件总线）
ACCOUNTS_URLtransactor/collaborator/workspacehttp://account:3000 或对外地址账号服务地址：内网调用用服务名，对外回调用 ${HOST_ADDRESS} 拼接
FRONT_URLtransactorhttp://localhost:8087前端地址
STATS_URLtransactor/collaborator/account/workspace/fulltexthttp://stats:4900 或对外用量上报地址
TRANSACTOR_URLaccount/workspacews://transactor:3333;ws${SECURE:+s}://${HOST_ADDRESS}/_transactor双地址分号串：分号前内网直连，分号后对外入口（经 nginx 反代路径 /_transactor）

3.2 检索与前端专属变量

变量出现的服务取值/说明
ELASTIC_URLfronthttp://elastic:9200
FULLTEXT_DB_URLfulltexthttp://elastic:9200（全文服务写索引的目标）
ELASTIC_INDEX_NAMEfulltexthuly_storage_index（实际建出 huly_storage_index_v2，由服务端命名策略决定）
REKONI_URLfulltexthttp://rekoni:4004（二进制文档解析服务，供附件全文提取）
UPLOAD_URLfront/files（上传路径前缀，nginx 转发到对象存储）
TITLE / DEFAULT_LANGUAGE / LAST_NAME_FIRSTfront顶层 2.3 节产品项注入
DISABLED_FEATURESfrontauto-translate,mailboxes（实测默认禁用自动翻译与邮箱功能）
DESKTOP_UPDATES_CHANNELfront${DESKTOP_CHANNEL}
MODEL_ENABLEDaccount/workspace*（启用全部领域模型；可用逗号清单收窄）

3.3 值得掌握的两个编排事实

  1. 工作区默认内容开关：新工作区默认初始化预置内容（示例文档等）。官方 README 提供关闭方法——给 workspace 服务加环境变量指向不存在的路径即可：
workspace:
  image: hardcoreeng/workspace:${HULY_VERSION}
  environment:
    # ...
    - INIT_REPO_DIR=/no-init-scripts
  1. 可选服务组：mongodb（AI 助手/日历需要）、redis + hulypulse（推送通知 HulyPulse 需要）在官方编排中默认注释。启用方式是去掉注释段并按需补 VOLUME_MONGO_PATH 等。基础项目管理功能（Tracker/Docs/Chat）不依赖这三者——本次实测 14 服务形态下全部核心功能可用。

四、账号初始化机制：Web 注册与管理 CLI

Huly 账号体系的存储形态：主库 global_account schema 的 person（人）、account（账号属性）、social_id（登录标识，email 类型即登录邮箱）、account_passwords（密码）等表。初始化有两条路径：

4.1 Web 注册（依赖 SMTP）

产品常规路径：入口页 Sign up → 填邮箱/姓名/密码 → 邮箱验证码 → 登录后创建或加入工作区。验证码由 account 服务经邮件服务下发，因此该路径要求配置 SMTP/邮件服务（官方仓库 guides/ 下有 SMTP 排障与 Gmail 配置指南；编排层需启用邮件服务并注入 MAIL_URL）。未配置邮件的实例，Sign up 会卡在验证码环节。

4.2 管理 CLI create-account（无邮件直落库）

管理工具（run-tool.sh 封装的 hardcoreeng/tool）创建账号直接写库且默认置为已验证，跳过邮箱验证码。实测：

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

数据库侧验证（social_id 落库、verified_on 已置值）：

type    value             key                    person_uuid                          created_on     verified_on
email   root@huly.local   email:root@huly.local  5ea0f331-f8bc-49ba-8b0c-28668f021b02 1793106270129  1793106270128

两个实测确认的行为边界：

  1. 密码策略宽松：q1w2e3r4（8 位纯字母数字）可被接受，无复杂度强制；
  2. 重复创建显式报错，不覆盖已有账号：
PlatformError: ERROR: platform:status:AccountAlreadyExists {}

工作区初始化配套命令（同为实测）：create-workspace demo "email:root@huly.local" 建工作区并指定所有者 social id；assign-workspace root@huly.local demo 把已有用户指派进工作区。完整命令矩阵见《Huly 常用 CLI 命令与运维实战》。

五、高频配置场景实操

5.1 从 HTTP 切换到 SSL

  1. huly_v7.conf：SECURE=true，HOST_ADDRESS 改为真实域名（443 端口经反代时可不带端口）；
  2. ./nginx.sh 重新生成反代配置，在生成结果上补 ssl_certificate/ssl_certificate_key 段；
  3. docker compose up -d 滚动重启应用服务（${SECURE:+s} 使服务间地址自动变 https/wss）。

5.2 修改对象存储凭据

编排中 STORAGE_CONFIG 写死 minioadmin/minioadmin。对象存储侧修改凭据后，需同步改 compose.yml 中所有服务的 STORAGE_CONFIG 值再 up -d——漏改任何一处都会出现「服务能起但附件读写失败」。

5.3 禁用新工作区默认内容

见 3.3 节第 1 条：workspace 服务加 INIT_REPO_DIR=/no-init-scripts。

5.4 配置变更生效路径速查

改动生效动作
顶层 conf 业务项（端口/地址/版本/凭据）docker compose up -d（滚动重建受影响服务）
接入相关（SECURE/HTTP_PORT/HOST_ADDRESS）先 ./nginx.sh 重生成反代配置，再 up -d
服务级 compose.yml 环境变量docker compose up -d 重建对应服务
SECRETup -d 后全员重新登录（旧令牌全部失效）
强依赖重启顺序依赖方（如 fulltext）在依赖恢复后 docker compose restart fulltext（部署篇排障实录四）

六、排障实录（配置视角）

6.1 Sign up 失败 / 卡验证码

官方 Troubleshooting 首条：页面能开但注册失败，先看 account 服务日志：

$ docker compose logs -f account

常见根因：HOST_ADDRESS 与实际访问地址不一致导致回调地址错误；或未配置邮件服务导致验证码无法下发。selfhost 未配 SMTP 时改用 4.2 节 CLI 路径初始化账号。

6.2 SSL wrong version number

SECURE=true 但入口实际提供 HTTP（或反代 TLS 配置缺失）时出现。核对反代证书配置、域名解析与 443 可达性；本地测试直接 SECURE= 复位为 HTTP 并重生成配置。

6.3 数据目录属主（bind mount 部署必踩）

自定义数据卷路径后，官方 README 的权限提醒（chown -R 1000:1000，redpanda 为 101）在实测中得到验证：redpanda 数据目录属主为 root 时启动报 error system:13, open: Permission denied（写 pid.lock 被拒）；Elasticsearch 数据目录属主为 root 时报 AccessDeniedException: /usr/share/elasticsearch/data/nodes。修复动作与完整根因链见《Huly 0.7.426 Docker Compose 部署实战》排障实录一、二——核心是镜像内运行用户 uid 与宿主机目录属主一致。

6.4 工具命令缺环境变量

管理工具的命令需要运行参数齐备。实测 fulltext-reindex 未注入 FULLTEXT_URL 时显式报错：

please provide FULLTEXT_URL

补齐方式（挂载时注入环境变量）：

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

6.5 数据库密码认证失败排查路径

实测排查数据时曾遇到 password authentication failed for user selfhost。定位顺序：① 确认用的是 CR_USER_PASSWORD（而非容器编排里其他密码变量）；② 客户端传密码的载体要与工具匹配（如 PGPASSWORD 环境变量或完整 URL）；③ CockroachDB 为 --accept-sql-without-tls 模式，连接串用 sslmode=disable 但仍需密码。最终以「PGPASSWORD=$CR_USER_PASSWORD + --url postgres://selfhost@...」组合实测连通。

七、本章小结

Huly 的配置面比典型 Web 应用宽：顶层 26 个 conf 变量 + 14 个服务各自的环境变量，再加三层分工。掌握三条主线即可覆盖绝大多数场景：接入层（HOST_ADDRESS/SECURE/端口 + nginx.sh 重生成）、数据层（CR_DB_URL/STORAGE_CONFIG/QUEUE_CONFIG/ELASTIC_URL 四类内网依赖串）、初始化层（SMTP 决定 Web 注册可用性，CLI create-account 是无邮件实例的兜底路径）。配置变更后按 5.4 速查表选择生效动作，可以避免绝大多数「改了没生效」问题。