From c157e9a418c2a76ea4b9acbae7d61339af23a8f7 Mon Sep 17 00:00:00 2001
From: cnphpbb <moqiruyi@126.com>
Date: Fri, 19 Jun 2026 18:39:17 +0800
Subject: [PATCH] =?UTF-8?q?fix(honcho):=20=E5=AE=B9=E5=99=A8=E7=AB=AF?=
 =?UTF-8?q?=E5=8F=A3=E5=BF=85=E9=A1=BB=E7=94=A8=E5=AE=B9=E5=99=A8=E5=86=85?=
 =?UTF-8?q?=E7=AB=AF=E5=8F=A3=EF=BC=8C=E4=B8=8D=E8=83=BD=E7=94=A8=20host?=
 =?UTF-8?q?=20=E6=98=A0=E5=B0=84=E7=AB=AF=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

vm61 honcho-api 一直 unhealthy + deriver 反复重启，根因是 stack.yml 把
宿主机映射端口 (HONCHO_DB_PORT=25432) 当成了容器间互访端口：
- DB_CONNECTION_URI 里 database:${HONCHO_DB_PORT} 应为 database:5432
- healthcheck URL localhost:18000 应为 localhost:8000
HONCHO_API_PORT/DB_PORT/REDIS_PORT 仅用于宿主机 ports 映射段，
容器之间互访必须硬编码容器内端口 (5432/6379/8000)。

- 改 stack.yml api + deriver 段 DB_CONNECTION_URI 端口为 5432
- 改 stack.yml api 段 healthcheck URL 为 localhost:8000
- readme 关键陷阱加第 6 条："容器端口 vs 宿主机端口不可混用"
- vm61 4 honcho 容器全部 healthy，deriver queue processor 已正常运行
---
 honcho/readme.md | 14 ++++++++++++++
 honcho/stack.yml |  6 +++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/honcho/readme.md b/honcho/readme.md
index f8e4723..be1f51b 100644
--- a/honcho/readme.md
+++ b/honcho/readme.md
@@ -253,6 +253,20 @@ Honcho 是 **AGPL-3.0**，对网络服务部署有"用户可获取源码"的要
 
 honcho-self-hosted 相对官方 compose 的一个改进：**移除了**`trust` 认证（官方默认的 dev 用法），改用强密码 + scram-sha-256。生产环境务必保留这个设置。
 
+### 6. 容器端口 vs 宿主机端口不可混用
+
+**容器之间互访必须用容器内端口（5432/6379/8000）**，不能用宿主机映射端口（如 `HONCHO_DB_PORT=25432`）。错误示例：
+
+```yaml
+# ❌ 错：${HONCHO_DB_PORT} 是宿主机端口 25432，容器内根本没监听这个
+DB_CONNECTION_URI=postgresql+psycopg://honcho:pw@database:${HONCHO_DB_PORT}/honcho
+
+# ✅ 对：硬编码容器内端口 5432
+DB_CONNECTION_URI=postgresql+psycopg://honcho:pw@database:5432/honcho
+```
+
+同样 healthcheck 也用容器内端口 `localhost:8000`，**不是** `localhost:18000`（宿主映射端口）。
+
 ## 故障排查
 
 | 症状 | 排查命令 |
diff --git a/honcho/stack.yml b/honcho/stack.yml
index 9541eab..bada9fc 100644
--- a/honcho/stack.yml
+++ b/honcho/stack.yml
@@ -35,7 +35,7 @@ services:
       - "${HONCHO_API_PORT:-8000}:8000"
     environment:
       - TZ=Asia/Shanghai
-      - DB_CONNECTION_URI=postgresql+psycopg://${HONCHO_DB_USER}:${HONCHO_DB_PASSWORD}@database:${HONCHO_DB_PORT}/${HONCHO_DB_NAME}
+      - DB_CONNECTION_URI=postgresql+psycopg://${HONCHO_DB_USER}:${HONCHO_DB_PASSWORD}@database:5432/${HONCHO_DB_NAME}
       - CACHE_URL=redis://redis:${HONCHO_REDIS_PORT}/0?suppress=true
       - CACHE_ENABLED=true
       - LOG_LEVEL=${HONCHO_LOG_LEVEL:-INFO}
@@ -64,7 +64,7 @@ services:
         - CMD
         - /app/.venv/bin/python
         - -c
-        - "import urllib.request; urllib.request.urlopen('http://localhost:18000/health', timeout=2).read()"
+        - "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=2).read()"
       interval: 10s
       timeout: 5s
       retries: 10
@@ -88,7 +88,7 @@ services:
         condition: service_healthy
     environment:
       - TZ=Asia/Shanghai
-      - DB_CONNECTION_URI=postgresql+psycopg://${HONCHO_DB_USER}:${HONCHO_DB_PASSWORD}@database:${HONCHO_DB_PORT}/${HONCHO_DB_NAME}
+      - DB_CONNECTION_URI=postgresql+psycopg://${HONCHO_DB_USER}:${HONCHO_DB_PASSWORD}@database:5432/${HONCHO_DB_NAME}
       - CACHE_URL=redis://redis:${HONCHO_REDIS_PORT}/0?suppress=true
       - CACHE_ENABLED=true
       - NAMESPACE=${HONCHO_NAMESPACE:-honcho}