容器：解决 Docker 在 Unraid 首次启动时数据库密码初始化竞态并补充排障文档

jingyi0605 · jingyi0605 · commit a5f79ed3fce5 · 2026-03-22T21:42:37.000+08:00
diff --git a/README.md b/README.md
@@ -243,10 +243,7 @@ bash start-open-xiaoai-gateway.sh
 
 | 配置项 | 说明 | 默认值 |
 |--------|------|--------|
-| `FAMILYCLAW_DATABASE_URL` | PostgreSQL 数据库地址 | Docker 首次启动自动生成随机密码，并持久化到 `/data/runtime/secrets/db-password` |
-| `FAMILYCLAW_HOME_ASSISTANT_BASE_URL` | Home Assistant 地址 | `http://127.0.0.1:8123` |
-| `FAMILYCLAW_HOME_ASSISTANT_TOKEN` | Home Assistant 长期访问令牌 | 需要手动填写 |
-| `FAMILYCLAW_AI_DEFAULT_PROVIDER_CODE` | 默认 AI 供应商 | `local-ollama` |
+| `FAMILYCLAW_DATABASE_URL` | PostgreSQL 数据库地址 | Docker 默认会把最终使用的数据库密码同步到 `/data/runtime/secrets/db-password`；如需自定义，优先传 `FAMILYCLAW_DB_PASSWORD`，不要让它和连接串里的密码打架 |
 | `FAMILYCLAW_VOICE_RUNTIME_MODE` | 语音模式 | `embedded`（本地处理） |
 
 ## 插件开发指南
@@ -603,10 +600,7 @@ bash start-open-xiaoai-gateway.sh
 
 | Setting | Description | Default |
 |---------|-------------|---------|
-| `FAMILYCLAW_DATABASE_URL` | PostgreSQL connection string | Docker auto-generates a random password on first start and stores it in `/data/runtime/secrets/db-password` |
-| `FAMILYCLAW_HOME_ASSISTANT_BASE_URL` | Home Assistant URL | `http://127.0.0.1:8123` |
-| `FAMILYCLAW_HOME_ASSISTANT_TOKEN` | Home Assistant long-lived access token | Must be set manually |
-| `FAMILYCLAW_AI_DEFAULT_PROVIDER_CODE` | Default AI provider | `local-ollama` |
+| `FAMILYCLAW_DATABASE_URL` | PostgreSQL connection string | Docker syncs the effective database password to `/data/runtime/secrets/db-password`; if you customize it, prefer `FAMILYCLAW_DB_PASSWORD` and keep it consistent with the password inside the URL |
 | `FAMILYCLAW_VOICE_RUNTIME_MODE` | Voice processing mode | `embedded` (local) |
 
 ## Plugin Development Guide
diff --git a/docker/scripts/common.sh b/docker/scripts/common.sh
@@ -28,6 +28,65 @@ log() {
   printf '[%s] %s\n' "${FAMILYCLAW_LOG_PREFIX}" "$1"
 }
 
+read_password_from_database_url() {
+  python - <<'PY'
+from __future__ import annotations
+
+import os
+from urllib.parse import urlsplit, unquote
+
+database_url = os.environ.get("FAMILYCLAW_DATABASE_URL", "").strip()
+if not database_url:
+    raise SystemExit(0)
+
+password = urlsplit(database_url).password
+if password:
+    print(unquote(password))
+PY
+}
+
+canonicalize_database_url() {
+  python - <<'PY'
+from __future__ import annotations
+
+import os
+from urllib.parse import quote, urlsplit, urlunsplit
+
+database_url = os.environ.get("FAMILYCLAW_DATABASE_URL", "").strip()
+password = os.environ["FAMILYCLAW_DB_PASSWORD"]
+
+if not database_url:
+    user = quote(os.environ.get("FAMILYCLAW_DB_USER", "familyclaw"), safe="")
+    host = os.environ.get("FAMILYCLAW_DB_HOST", "127.0.0.1")
+    port = os.environ.get("FAMILYCLAW_DB_PORT", "5432")
+    database_name = quote(os.environ.get("FAMILYCLAW_DB_NAME", "familyclaw"), safe="/")
+    encoded_password = quote(password, safe="")
+    print(f"postgresql+psycopg://{user}:{encoded_password}@{host}:{port}/{database_name}")
+    raise SystemExit(0)
+
+parts = urlsplit(database_url)
+scheme = parts.scheme or "postgresql+psycopg"
+username = parts.username or os.environ.get("FAMILYCLAW_DB_USER", "familyclaw")
+hostname = parts.hostname or os.environ.get("FAMILYCLAW_DB_HOST", "127.0.0.1")
+port = parts.port
+path = parts.path or f"/{quote(os.environ.get('FAMILYCLAW_DB_NAME', 'familyclaw'), safe='')}"
+
+userinfo = quote(username, safe="")
+if password:
+    userinfo = f"{userinfo}:{quote(password, safe='')}"
+
+hostpart = hostname
+if ":" in hostname and not hostname.startswith("["):
+    hostpart = f"[{hostname}]"
+
+netloc = f"{userinfo}@{hostpart}"
+if port is not None:
+    netloc = f"{netloc}:{port}"
+
+print(urlunsplit((scheme, netloc, path, parts.query, parts.fragment)))
+PY
+}
+
 generate_secret() {
   local token_bytes="${1:-32}"
   python - "${token_bytes}" <<'PY'
@@ -56,12 +115,40 @@ write_secret_file() {
   chmod 600 "${secret_file}"
 }
 
+acquire_secret_lock() {
+  local lock_dir="$1"
+  local max_attempts="${2:-300}"
+  local attempt=0
+  local lock_parent
+
+  lock_parent="$(dirname "${lock_dir}")"
+  mkdir -p "${lock_parent}"
+
+  while ! mkdir "${lock_dir}" 2>/dev/null; do
+    attempt=$((attempt + 1))
+    if [[ "${attempt}" -ge "${max_attempts}" ]]; then
+      log "Timed out waiting for secret lock ${lock_dir}"
+      return 1
+    fi
+    sleep 0.1
+  done
+}
+
+release_secret_lock() {
+  local lock_dir="$1"
+  rmdir "${lock_dir}" 2>/dev/null || true
+}
+
 load_or_create_secret() {
   local var_name="$1"
   local secret_file="$2"
   local secret_label="$3"
   local token_bytes="${4:-32}"
   local current_value="${!var_name:-}"
+  local lock_dir="${secret_file}.lock"
+
+  # 首次启动时多个服务会并发 source 本脚本，这里必须串行化 secret 初始化。
+  acquire_secret_lock "${lock_dir}"
 
   if [[ -n "${current_value}" ]]; then
     write_secret_file "${secret_file}" "${current_value}"
@@ -74,6 +161,8 @@ load_or_create_secret() {
     log "Generated and persisted ${secret_label} at ${secret_file}"
   fi
 
+  release_secret_lock "${lock_dir}"
+
   printf -v "${var_name}" '%s' "${current_value}"
   export "${var_name}"
 }
@@ -85,10 +174,18 @@ is_truthy() {
   esac
 }
 
+if [[ -z "${FAMILYCLAW_DB_PASSWORD:-}" && -n "${FAMILYCLAW_DATABASE_URL:-}" ]]; then
+  parsed_db_password="$(read_password_from_database_url || true)"
+  if [[ -n "${parsed_db_password}" ]]; then
+    export FAMILYCLAW_DB_PASSWORD="${parsed_db_password}"
+    log "Using database password parsed from FAMILYCLAW_DATABASE_URL"
+  fi
+fi
+
 load_or_create_secret FAMILYCLAW_DB_PASSWORD "${FAMILYCLAW_DB_PASSWORD_FILE}" "database password" 24
 load_or_create_secret FAMILYCLAW_VOICE_GATEWAY_TOKEN "${FAMILYCLAW_VOICE_GATEWAY_TOKEN_FILE}" "voice gateway token" 32
 
-export FAMILYCLAW_DATABASE_URL="${FAMILYCLAW_DATABASE_URL:-postgresql+psycopg://${FAMILYCLAW_DB_USER}:${FAMILYCLAW_DB_PASSWORD}@${FAMILYCLAW_DB_HOST}:${FAMILYCLAW_DB_PORT}/${FAMILYCLAW_DB_NAME}}"
+export FAMILYCLAW_DATABASE_URL="$(canonicalize_database_url)"
 export FAMILYCLAW_PLUGIN_STORAGE_ROOT="${FAMILYCLAW_PLUGIN_STORAGE_ROOT:-${FAMILYCLAW_PLUGIN_DATA_DIR}}"
 export FAMILYCLAW_PLUGIN_MARKETPLACE_INSTALL_ROOT="${FAMILYCLAW_PLUGIN_MARKETPLACE_INSTALL_ROOT:-${FAMILYCLAW_PLUGIN_DATA_DIR}}"
 export FAMILYCLAW_VOICE_RUNTIME_ARTIFACTS_ROOT="${FAMILYCLAW_VOICE_RUNTIME_ARTIFACTS_ROOT:-${FAMILYCLAW_VOICE_ARTIFACTS_DIR}}"
diff --git a/docs/Documentation/en/getting-started/quick-start.md b/docs/Documentation/en/getting-started/quick-start.md
@@ -36,7 +36,7 @@ docker run -d \
 
 This documentation uses `latest` as the default install entry. Only pin a concrete tag when you need precise rollback, issue reproduction, or a fixed release target.
 
-3. On first start, the container generates a random database password and voice gateway token, then stores them under `/srv/familyclaw-data/runtime/secrets/`. About one minute later, open `http://<server-ip>:8080` in a browser. If the login page appears, the system is up.
+3. On first start, the container generates a random database password and voice gateway token, then stores them under `/srv/familyclaw-data/runtime/secrets/`. If you customize the database password, prefer `FAMILYCLAW_DB_PASSWORD`; when `FAMILYCLAW_DATABASE_URL` is also present, the password in both places must stay consistent. About one minute later, open `http://<server-ip>:8080` in a browser. If the login page appears, the system is up.
 4. The initial account is `user` / `user`. After login, follow the setup flow to change the account and password.
 
 Placeholder for screenshot: login page after Docker startup
diff --git a/docs/Documentation/en/installation-deployment/docker-installation.md b/docs/Documentation/en/installation-deployment/docker-installation.md
@@ -46,6 +46,7 @@ On first start, the container auto-generates a random database password and a ra
 - `/data/runtime/secrets/voice-gateway-token`
 
 If you want to take over either value yourself, you can still pass `FAMILYCLAW_DB_PASSWORD` or `FAMILYCLAW_VOICE_GATEWAY_TOKEN`. The container will use your value and sync it back into the same secrets files.
+If you also pass `FAMILYCLAW_DATABASE_URL`, the container now syncs the password inside that URL to the same canonical secret. Do not keep different passwords in `FAMILYCLAW_DB_PASSWORD` and the URL, because older images can fail to start that way.
 
 ## Verify after startup
 
@@ -59,7 +60,8 @@ If you want to take over either value yourself, you can still pass `FAMILYCLAW_D
 
 - Cannot reach port 8080: check your firewall or whether another service already uses the port.
 - The container does not start: make sure the image pulled successfully, or remove the old container first with `docker rm -f familyclaw`.
-- Login shows database errors: confirm `/data/runtime/secrets/db-password` was created and the mounted data volume is writable.
+- Login shows database errors: confirm `/data/runtime/secrets/db-password` was created and the mounted data volume is writable. If you customized the database connection, verify that `FAMILYCLAW_DB_PASSWORD` matches the password embedded in `FAMILYCLAW_DATABASE_URL`.
+- Fresh Unraid or NAS deployment still shows `password authentication failed for user "familyclaw"`: this is usually not stale data. Older images can hit a first-start race while generating the database password. Update to an image with the fix; if you must stay on the older image for now, explicitly pass the same value in both `FAMILYCLAW_DB_PASSWORD` and `FAMILYCLAW_DATABASE_URL`.
 - Voice-related errors while you do not use voice: you can skip the `4399` port mapping and ignore voice gateway logs.
 
 ## Uninstall
diff --git a/docs/Documentation/安装部署/Docker安装.md b/docs/Documentation/安装部署/Docker安装.md
@@ -46,6 +46,7 @@ docker run -d \
 - `/data/runtime/secrets/voice-gateway-token`
 
 如果你明确要接管这两个值，仍然可以手工传 `FAMILYCLAW_DB_PASSWORD` 和 `FAMILYCLAW_VOICE_GATEWAY_TOKEN`；容器会优先使用你传入的值并同步回上面的 secrets 文件。
+如果你还额外传了 `FAMILYCLAW_DATABASE_URL`，容器也会把里面的数据库密码同步成同一个值；不要再让 `FAMILYCLAW_DB_PASSWORD` 和连接串密码写成两个不同值，否则旧版本会直接把自己搞挂。
 
 ## 启动后验证
 
@@ -59,7 +60,8 @@ docker run -d \
 
 - 访问不到 8080：检查防火墙或端口是否被占用。
 - 无法启动容器：确认 Docker 拉镜像成功，或清理旧同名容器 `docker rm -f familyclaw`。
-- 登录后提示数据库错误：先确认 `/data/runtime/secrets/db-password` 已生成，再确认数据卷可写。
+- 登录后提示数据库错误：先确认 `/data/runtime/secrets/db-password` 已生成，再确认数据卷可写；如果你自定义过数据库连接，检查 `FAMILYCLAW_DB_PASSWORD` 和 `FAMILYCLAW_DATABASE_URL` 里的密码是否一致。
+- Unraid / NAS 上全新部署仍然报 `password authentication failed for user "familyclaw"`：这通常不是旧数据没删干净，而是旧镜像在首次启动时撞上了数据库密码初始化竞态。更新到包含修复的镜像；如果暂时只能用旧镜像，先显式传同一个 `FAMILYCLAW_DB_PASSWORD` 与 `FAMILYCLAW_DATABASE_URL` 规避。
 - 语音相关报错但不用语音：可不映射 4399 端口，忽略语音网关日志。
 
 ## 需要卸载
diff --git a/docs/Documentation/快速开始/快速启动.md b/docs/Documentation/快速开始/快速启动.md
@@ -38,7 +38,7 @@ docker run -d \
 
 这里默认写 `latest`，让安装文档保持稳定。只有在你要精确回滚、复现旧版本问题，或者明确锁定某个发布版时，才改成具体版本标签。
 
-4. 第一次启动时，系统会自动生成需要的密钥信息，并写入 `/srv/familyclaw-data/runtime/secrets/`。
+4. 第一次启动时，系统会自动生成需要的密钥信息，并写入 `/srv/familyclaw-data/runtime/secrets/`。如果你要自定义数据库密码，优先传 `FAMILYCLAW_DB_PASSWORD`；如果同时传了 `FAMILYCLAW_DATABASE_URL`，两边密码必须一致。
 5. 等大约 1 分钟后，在浏览器打开 `http://服务器IP:8080`。如果你已经看到登录页，说明系统已经跑起来了。
 6. 初始账号是 `user`，初始密码也是 `user`。第一次登录后，按页面引导继续完成初始化，并尽快改掉默认账号密码。
 
