fix(docker): manage local postgres in default compose

docker-compose.postgres.yml

@@ -1,36 +1,4 @@
-services:
+# PostgreSQL 已并入默认 docker-compose.yml。
-  main:
+# 保留此空覆盖文件，兼容历史启动命令：
-    depends_on:
+# docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d
-      postgres:
+services: {}
-        condition: service_healthy
-    environment:
-      POSTGRES_HOST: postgres
-      POSTGRES_PORT: "5432"
-      POSTGRES_DB: "${POSTGRES_DB:-x_financial}"
-      POSTGRES_USER: "${POSTGRES_USER:-x_financial}"
-      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-x_financial}"
-      DATABASE_URL: "postgresql+psycopg://${POSTGRES_USER:-x_financial}:${POSTGRES_PASSWORD:-x_financial}@postgres:5432/${POSTGRES_DB:-x_financial}"
-
-  postgres:
-    image: pgvector/pgvector:pg17
-    container_name: x-financial-postgres
-    restart: unless-stopped
-    environment:
-      POSTGRES_DB: "${POSTGRES_DB:-x_financial}"
-      POSTGRES_USER: "${POSTGRES_USER:-x_financial}"
-      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-x_financial}"
-    ports:
-      - "${POSTGRES_HOST_PORT:-55432}:5432"
-    volumes:
-      - postgres-data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
-      interval: 15s
-      timeout: 5s
-      retries: 10
-      start_period: 30s
-    networks:
-      - financial-internal
-
-volumes:
-  postgres-data:

docker-compose.yml

@@ -3,6 +3,9 @@ services:
     image: x-financial-dev:latest
     container_name: local-x-financial-linux
     restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
     environment:
       WEB_HOST: 0.0.0.0
       WEB_PORT: "${WEB_PORT:-5173}"
@@ -11,6 +14,12 @@ services:
       SERVER_RELOAD: "${SERVER_RELOAD:-true}"
       SERVER_VENV_DIR: /tmp/x-financial-server-venv
       X_FINANCIAL_PREFER_ENV_FILE: "true"
+      POSTGRES_HOST: postgres
+      POSTGRES_PORT: "5432"
+      POSTGRES_DB: "${LOCAL_POSTGRES_DB:-x_financial}"
+      POSTGRES_USER: "${LOCAL_POSTGRES_USER:-x_financial}"
+      POSTGRES_PASSWORD: "${LOCAL_POSTGRES_PASSWORD:-x_financial}"
+      DATABASE_URL: "postgresql+psycopg://${LOCAL_POSTGRES_USER:-x_financial}:${LOCAL_POSTGRES_PASSWORD:-x_financial}@postgres:5432/${LOCAL_POSTGRES_DB:-x_financial}"
       ONLYOFFICE_ENABLED: "${ONLYOFFICE_ENABLED:-false}"
       ONLYOFFICE_PUBLIC_URL: "${ONLYOFFICE_PUBLIC_URL:-}"
       ONLYOFFICE_BACKEND_URL: "${ONLYOFFICE_BACKEND_URL:-}"
@@ -65,6 +74,30 @@ services:
     networks:
       - financial-internal
 
+  postgres:
+    image: pgvector/pgvector:pg17
+    container_name: x-financial-local-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: "${LOCAL_POSTGRES_DB:-x_financial}"
+      POSTGRES_USER: "${LOCAL_POSTGRES_USER:-x_financial}"
+      POSTGRES_PASSWORD: "${LOCAL_POSTGRES_PASSWORD:-x_financial}"
+    ports:
+      - "127.0.0.1:${LOCAL_POSTGRES_HOST_PORT:-55432}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    networks:
+      - financial-internal
+
 networks:
   financial-internal:
     name: financial-internal
+
+volumes:
+  postgres-data:

document/development/2026-07-17/dev-logs/bugs/default-compose-local-postgres-lifecycle.md

@@ -0,0 +1,15 @@
+# 默认 Compose 未统一管理本地 PostgreSQL
+
+日期：2026-07-17
+文档路径：document/development/2026-07-17/dev-logs/bugs/default-compose-local-postgres-lifecycle.md
+
+## 修复记录
+- 22:47：记录 bug 修复：默认 Compose 未统一管理本地 PostgreSQL。（bug-log:787bc3a4）
+  - Git 提交检查：fetch 成功；upstream `origin/main`；upstream 新提交：未发现；本地 ahead 提交：787bc3a4 (HEAD -> main) feat(platform): close AI expense value loop；242d68c3 feat(approval): add task workflow and waiver decisions；28b834ed fix(approval): replay immutable action responses；4940ebc4 feat(approval): add safe risk disposition workflow；ee88a36b feat(ai): add tenant-safe hierarchical expense learning；6bdf65bc feat(expenses): add authoritative pre-review workflow；ae3f02c3 feat(expense): add persistent zero-entry receipt association；54754b55 feat(ai): add personal expense application memory；... 另有 10 条。
+  - 修改：`docker-compose.yml` 将 PostgreSQL、健康依赖、本机端口和持久卷并入默认启动链路；本地数据库插值改用独立的 `LOCAL_POSTGRES_*` 命名空间，避免根 `.env` 的外部数据库账号污染 Compose；`docker-compose.postgres.yml` 保留为空兼容覆盖文件。
+  - 修改：`start.sh` 与 `server_start.sh` 在读取 `.env` 前保存并在读取后恢复完整 PostgreSQL 运行参数，保证 Compose 注入的 host、port、database、user、password 和 URL 始终优先；`test_env_file_precedence.py` 增加根脚本、后端脚本和默认 Compose 回归。
+  - 操作：先将旧库备份到 `/tmp/x-financial-local-pre-compose-20260717.dump`，再把旧卷只读复制到 Compose 管理的 `x-financial_postgres-data`；旧卷未删除。统一本地开发角色凭据后执行 `docker compose up -d`，迁移前置检查从 `unversioned/base` 通过并升级到 `20260717_0028`。
+  - 过程披露：第一次 Compose 重建暴露环境优先级问题时，主容器仍沿用了根 `.env` 指向的外部数据库，并按既有启动流程将其从 `20260716_0006` 升级到 `20260717_0028`；迁移日志无失败，未对外部库执行回滚。修复后已确认当前主容器只连接本地 PostgreSQL 容器。
+  - 验证：容器内定向测试 `107 passed`；Ruff、格式、两个 shell 脚本语法、默认/兼容 Compose 配置和 `git diff --check` 均通过；重复执行 `docker compose up -d` 只保持两个服务运行，没有创建额外容器。
+  - 验证：`main` 与 `postgres` 均为 healthy；前端代理健康接口返回数据库 `ok=true`；应用实际连接 PostgreSQL 容器地址；本地库为 85 张 public 表、105 条员工数据、Alembic head `20260717_0028`，PostgreSQL 日志无 FATAL/ERROR/PANIC。
+  - 影响：以后在仓库根目录执行一次默认 `docker compose up -d` 即可同时启动应用和本地数据库，并复用 Compose 管理的数据卷；外部数据库 `.env` 配置不再悄悄覆盖本地 Compose 连接。

server/server_start.sh

@@ -90,6 +90,10 @@ fi
 ENV_OVERRIDE_SERVER_HOST_SET=false
 ENV_OVERRIDE_SERVER_PORT_SET=false
 ENV_OVERRIDE_POSTGRES_HOST_SET=false
+ENV_OVERRIDE_POSTGRES_PORT_SET=false
+ENV_OVERRIDE_POSTGRES_DB_SET=false
+ENV_OVERRIDE_POSTGRES_USER_SET=false
+ENV_OVERRIDE_POSTGRES_PASSWORD_SET=false
 ENV_OVERRIDE_DATABASE_URL_SET=false
 ENV_OVERRIDE_STARTUP_BOOTSTRAP_ENABLED_SET=false
 ENV_OVERRIDE_BACKGROUND_SCHEDULERS_ENABLED_SET=false
@@ -120,6 +124,26 @@ if [ "${POSTGRES_HOST+x}" = x ]; then
     ENV_OVERRIDE_POSTGRES_HOST="$POSTGRES_HOST"
 fi
 
+if [ "${POSTGRES_PORT+x}" = x ]; then
+    ENV_OVERRIDE_POSTGRES_PORT_SET=true
+    ENV_OVERRIDE_POSTGRES_PORT="$POSTGRES_PORT"
+fi
+
+if [ "${POSTGRES_DB+x}" = x ]; then
+    ENV_OVERRIDE_POSTGRES_DB_SET=true
+    ENV_OVERRIDE_POSTGRES_DB="$POSTGRES_DB"
+fi
+
+if [ "${POSTGRES_USER+x}" = x ]; then
+    ENV_OVERRIDE_POSTGRES_USER_SET=true
+    ENV_OVERRIDE_POSTGRES_USER="$POSTGRES_USER"
+fi
+
+if [ "${POSTGRES_PASSWORD+x}" = x ]; then
+    ENV_OVERRIDE_POSTGRES_PASSWORD_SET=true
+    ENV_OVERRIDE_POSTGRES_PASSWORD="$POSTGRES_PASSWORD"
+fi
+
 if [ "${DATABASE_URL+x}" = x ]; then
     ENV_OVERRIDE_DATABASE_URL_SET=true
     ENV_OVERRIDE_DATABASE_URL="$DATABASE_URL"
@@ -171,6 +195,22 @@ if [ "$ENV_OVERRIDE_POSTGRES_HOST_SET" = true ]; then
     POSTGRES_HOST="$ENV_OVERRIDE_POSTGRES_HOST"
 fi
 
+if [ "$ENV_OVERRIDE_POSTGRES_PORT_SET" = true ]; then
+    POSTGRES_PORT="$ENV_OVERRIDE_POSTGRES_PORT"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_DB_SET" = true ]; then
+    POSTGRES_DB="$ENV_OVERRIDE_POSTGRES_DB"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_USER_SET" = true ]; then
+    POSTGRES_USER="$ENV_OVERRIDE_POSTGRES_USER"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_PASSWORD_SET" = true ]; then
+    POSTGRES_PASSWORD="$ENV_OVERRIDE_POSTGRES_PASSWORD"
+fi
+
 if [ "$ENV_OVERRIDE_DATABASE_URL_SET" = true ]; then
     DATABASE_URL="$ENV_OVERRIDE_DATABASE_URL"
 fi

server/tests/test_env_file_precedence.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from pathlib import Path
 import os
 import subprocess
+from pathlib import Path
 
 
 def _run_script_prefix(
@@ -81,6 +81,46 @@ def test_root_start_can_prefer_env_file_over_inherited_onlyoffice_values(tmp_pat
     assert "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082" in result.stdout
 
 
+def test_root_start_preserves_inherited_database_runtime_values(tmp_path: Path) -> None:
+    result = _run_script_prefix(
+        tmp_path,
+        "start.sh",
+        env_file_content=(
+            "POSTGRES_HOST=external-db\n"
+            "POSTGRES_PORT=6432\n"
+            "POSTGRES_DB=external_financial\n"
+            "POSTGRES_USER=external_user\n"
+            "POSTGRES_PASSWORD=external_password\n"
+            "DATABASE_URL=postgresql://external_user:external_password@external-db:6432/external_financial\n"
+        ),
+        env={
+            "POSTGRES_HOST": "postgres",
+            "POSTGRES_PORT": "5432",
+            "POSTGRES_DB": "x_financial",
+            "POSTGRES_USER": "x_financial",
+            "POSTGRES_PASSWORD": "x_financial",
+            "DATABASE_URL": "postgresql://x_financial:x_financial@postgres:5432/x_financial",
+        },
+        output_vars=[
+            "POSTGRES_HOST",
+            "POSTGRES_PORT",
+            "POSTGRES_DB",
+            "POSTGRES_USER",
+            "POSTGRES_PASSWORD",
+            "DATABASE_URL",
+        ],
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "POSTGRES_HOST=postgres" in result.stdout
+    assert "POSTGRES_PORT=5432" in result.stdout
+    assert "POSTGRES_DB=x_financial" in result.stdout
+    assert "POSTGRES_USER=x_financial" in result.stdout
+    assert "POSTGRES_PASSWORD=x_financial" in result.stdout
+    expected_database_url = "postgresql://x_financial:x_financial@postgres:5432/x_financial"
+    assert f"DATABASE_URL={expected_database_url}" in result.stdout
+
+
 def test_web_start_preserves_inherited_runtime_ports(tmp_path: Path) -> None:
     result = _run_script_prefix(
         tmp_path,
@@ -139,3 +179,59 @@ def test_server_start_preserves_inherited_runtime_guards(tmp_path: Path) -> None
     assert "SERVER_PORT=8000" in result.stdout
     assert "STARTUP_BOOTSTRAP_ENABLED=false" in result.stdout
     assert "BACKGROUND_SCHEDULERS_ENABLED=false" in result.stdout
+
+
+def test_server_start_preserves_inherited_database_runtime_values(tmp_path: Path) -> None:
+    result = _run_script_prefix(
+        tmp_path,
+        "server/server_start.sh",
+        env_file_content=(
+            "POSTGRES_HOST=external-db\n"
+            "POSTGRES_PORT=6432\n"
+            "POSTGRES_DB=external_financial\n"
+            "POSTGRES_USER=external_user\n"
+            "POSTGRES_PASSWORD=external_password\n"
+            "DATABASE_URL=postgresql://external_user:external_password@external-db:6432/external_financial\n"
+        ),
+        env={
+            "POSTGRES_HOST": "postgres",
+            "POSTGRES_PORT": "5432",
+            "POSTGRES_DB": "x_financial",
+            "POSTGRES_USER": "x_financial",
+            "POSTGRES_PASSWORD": "x_financial",
+            "DATABASE_URL": "postgresql://x_financial:x_financial@postgres:5432/x_financial",
+        },
+        output_vars=[
+            "POSTGRES_HOST",
+            "POSTGRES_PORT",
+            "POSTGRES_DB",
+            "POSTGRES_USER",
+            "POSTGRES_PASSWORD",
+            "DATABASE_URL",
+        ],
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "POSTGRES_HOST=postgres" in result.stdout
+    assert "POSTGRES_PORT=5432" in result.stdout
+    assert "POSTGRES_DB=x_financial" in result.stdout
+    assert "POSTGRES_USER=x_financial" in result.stdout
+    assert "POSTGRES_PASSWORD=x_financial" in result.stdout
+    expected_database_url = "postgresql://x_financial:x_financial@postgres:5432/x_financial"
+    assert f"DATABASE_URL={expected_database_url}" in result.stdout
+
+
+def test_default_compose_isolates_local_postgres_from_external_env_values() -> None:
+    compose = (Path(__file__).resolve().parents[2] / "docker-compose.yml").read_text(
+        encoding="utf-8"
+    )
+
+    assert "condition: service_healthy" in compose
+    assert "container_name: x-financial-local-postgres" in compose
+    assert "${LOCAL_POSTGRES_DB:-x_financial}" in compose
+    assert "${LOCAL_POSTGRES_USER:-x_financial}" in compose
+    assert "${LOCAL_POSTGRES_PASSWORD:-x_financial}" in compose
+    assert "${LOCAL_POSTGRES_HOST_PORT:-55432}" in compose
+    assert "${POSTGRES_DB:-x_financial}" not in compose
+    assert "${POSTGRES_USER:-x_financial}" not in compose
+    assert "${POSTGRES_PASSWORD:-x_financial}" not in compose

start.sh

@@ -48,6 +48,12 @@ fi
 
 ENV_OVERRIDE_WEB_HOST_SET=false
 ENV_OVERRIDE_SERVER_HOST_SET=false
+ENV_OVERRIDE_POSTGRES_HOST_SET=false
+ENV_OVERRIDE_POSTGRES_PORT_SET=false
+ENV_OVERRIDE_POSTGRES_DB_SET=false
+ENV_OVERRIDE_POSTGRES_USER_SET=false
+ENV_OVERRIDE_POSTGRES_PASSWORD_SET=false
+ENV_OVERRIDE_DATABASE_URL_SET=false
 ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET=false
 ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL_SET=false
 ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL_SET=false
@@ -70,6 +76,36 @@ if [ "${SERVER_HOST+x}" = x ]; then
   ENV_OVERRIDE_SERVER_HOST="$SERVER_HOST"
 fi
 
+if [ "${POSTGRES_HOST+x}" = x ]; then
+  ENV_OVERRIDE_POSTGRES_HOST_SET=true
+  ENV_OVERRIDE_POSTGRES_HOST="$POSTGRES_HOST"
+fi
+
+if [ "${POSTGRES_PORT+x}" = x ]; then
+  ENV_OVERRIDE_POSTGRES_PORT_SET=true
+  ENV_OVERRIDE_POSTGRES_PORT="$POSTGRES_PORT"
+fi
+
+if [ "${POSTGRES_DB+x}" = x ]; then
+  ENV_OVERRIDE_POSTGRES_DB_SET=true
+  ENV_OVERRIDE_POSTGRES_DB="$POSTGRES_DB"
+fi
+
+if [ "${POSTGRES_USER+x}" = x ]; then
+  ENV_OVERRIDE_POSTGRES_USER_SET=true
+  ENV_OVERRIDE_POSTGRES_USER="$POSTGRES_USER"
+fi
+
+if [ "${POSTGRES_PASSWORD+x}" = x ]; then
+  ENV_OVERRIDE_POSTGRES_PASSWORD_SET=true
+  ENV_OVERRIDE_POSTGRES_PASSWORD="$POSTGRES_PASSWORD"
+fi
+
+if [ "${DATABASE_URL+x}" = x ]; then
+  ENV_OVERRIDE_DATABASE_URL_SET=true
+  ENV_OVERRIDE_DATABASE_URL="$DATABASE_URL"
+fi
+
 if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_ENABLED+x}" = x ]; then
   ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET=true
   ENV_OVERRIDE_ONLYOFFICE_ENABLED="$ONLYOFFICE_ENABLED"
@@ -102,6 +138,30 @@ if [ "$ENV_OVERRIDE_SERVER_HOST_SET" = true ]; then
   SERVER_HOST="$ENV_OVERRIDE_SERVER_HOST"
 fi
 
+if [ "$ENV_OVERRIDE_POSTGRES_HOST_SET" = true ]; then
+  POSTGRES_HOST="$ENV_OVERRIDE_POSTGRES_HOST"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_PORT_SET" = true ]; then
+  POSTGRES_PORT="$ENV_OVERRIDE_POSTGRES_PORT"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_DB_SET" = true ]; then
+  POSTGRES_DB="$ENV_OVERRIDE_POSTGRES_DB"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_USER_SET" = true ]; then
+  POSTGRES_USER="$ENV_OVERRIDE_POSTGRES_USER"
+fi
+
+if [ "$ENV_OVERRIDE_POSTGRES_PASSWORD_SET" = true ]; then
+  POSTGRES_PASSWORD="$ENV_OVERRIDE_POSTGRES_PASSWORD"
+fi
+
+if [ "$ENV_OVERRIDE_DATABASE_URL_SET" = true ]; then
+  DATABASE_URL="$ENV_OVERRIDE_DATABASE_URL"
+fi
+
 if [ "$ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET" = true ]; then
   ONLYOFFICE_ENABLED="$ENV_OVERRIDE_ONLYOFFICE_ENABLED"
 fi