📝 docs: Simplify docker compose network architecture & Remove broken links from docker compose docs (#12749)

* ♻️ refactor(docker): simplify network architecture and add admin port - Remove unnecessary network-service (alpine) container - Use dedicated lobe-network bridge for all services - Add RUSTFS_ADMIN_PORT environment variable for admin console - Update container-to-container communication to use Docker service names - Use relative path volumes for better data persistence * 📝 docs: update Docker Compose deployment guide - Add single-domain deployment documentation - Update INTERNAL_APP_URL guidance - Clarify Port Mode vs Domain Mode behavior - Add S3_ENDPOINT configuration tips - Remove broken link to non-existent server-database documentation * fix(docker): keep backward-compatible volume paths for existing deployments - PostgreSQL: Keep ./data (not ./postgres_data) - Redis: Keep redis_data named volume (not ./redis_data) - RustFS: Keep rustfs-data named volume (not ./rustfs_data) This ensures existing users can upgrade without data migration. * fix(docker): correct Port Mode vs Domain Mode description - Fix reversed explanation in comments - Port Mode: Uses default ports (3210/9000/9001) - Domain Mode: Custom ports via reverse proxy This aligns with the actual deployment script behavior.
2026-03-26 13:19:34 +07:00 · 2026-03-10 09:55:56 +08:00
parent ea329113be
commit 023e3ef11a
5 changed files with 95 additions and 68 deletions
--- a/docker-compose/deploy/.env.example
+++ b/docker-compose/deploy/.env.example
@@ -17,6 +17,7 @@
 # if no special requirements, no need to change
 LOBE_PORT=3210
 RUSTFS_PORT=9000
+RUSTFS_ADMIN_PORT=9001
 APP_URL=http://localhost:3210
 # INTERNAL_APP_URL is optional, used for server-to-server calls
 # to bypass CDN/proxy. If not set, defaults to APP_URL.
@@ -31,11 +32,11 @@ LOBE_DB_NAME=lobechat
 POSTGRES_PASSWORD=uWNZugjBqixf8dxC

 # RUSTFS S3 configuration
+S3_ENDPOINT=http://localhost:9000
 RUSTFS_ACCESS_KEY=admin
 RUSTFS_SECRET_KEY=YOUR_RUSTFS_PASSWORD

 # Configure the bucket information of RUSTFS
-S3_ENDPOINT=http://localhost:9000
 RUSTFS_LOBE_BUCKET=lobe

 JWKS_KEY={"keys":[{"d":"PVoFyqyrGstB8wU52S7gqqQQdZLtin_thcEM0nrNtqp9U-NlKLlhgEcWp5t89ycgvhsAzmrRbezGj4JBTr3jn7eWdwQpPJNYiipnsgeJn0pwsB0H2dMqtavxinoPVXkMTOuGHMTFhhyguFBw2JbIL0PTQUcUlXjv40OoJpYHZeggSxgfV-TuxjwW8Ll4-n84M5IOi6A53RvioE-Hm1iyIc2XLBCfyOu-SbAQYi8HzrA64kCxobAB0peLQMiAzfZmwPKiGOhnhKrAlYmG02qFnbUYiJu_-AXwsAyGv9S9i6dwK7QXaGGWYyis8LlPpd_JmPrBnrWomwDlI045NUMWZQ","dp":"OSXI2NBBZl2r0Dpf4-1z44A_jC5lOyXtJhXQYnSXy5eIuxTJcEtkUYagGEwnREO4Q3t-4J-lT_6Y71M1ZlgKG1upwfw1O4aE3vGpHOik9iZYYCjA8fe5uBfOpX1ELmOtHNoHRhMtyjuPxSFXLlSp3bgcF1f3F40ClukdvXCx0Mc","dq":"m6hNdfj-F8E_7nUlX2nG95OffkFrhHTo67ML9aPgpvFwBlzg-hk5LwtxMfUzngqWF78TMl0JDm7vS1bz0xlWqXqu8pFPoTUnUoWgYfvuyHLBwR5TgccQkfoKbkSMzYNy8VJPXZeyIjVXsW98tZvj-NZF-M9Pke_EWJm-jjXCu_8","e":"AQAB","kty":"RSA","n":"piffosMS0HOSgsSr_zQkXYaQt1kOCD73VR0b2XJD6UdQCKPbnBOzTIuA_xowX61QVsl5pCZLTw8ERC3r2Nlxj5Rp_H6RuOT7ioUqlbnxSGnfuAn8dFupY3A-sf9HVDOvtJdlS-nO9yA4wWU-A50zZ1Mf0pPZlUZE6dUQfsJFi5yXaNAybyk3U4VpMO_SXAilWEHVhiO0F0ccpJMCkT47AeXmYH9MlWwIGcay0UiAsdrs8J-q1arZ7Mbq0oxHmUXJG0vwRvAL8KnCEi8cJ3e2kKCRcr-BQCujsHUyUl6f_ATwSVuTHdAR1IzIcW37v27h3WQK_v0ffQM1NstamDX5vQ","p":"4myVm2M5cZGvVXsOmWUTUG87VC1GlQcL5tmMNSGSpQCL8yWZ1vANkmCxSMptrKB4dU9DAB3On6_oMhW1pJ3uYNGSW49BcmJoLkiWKeg5zWFnKPQNuThQmY1sCCubtKhBQgaYUr7TVzN9smrDV3zCu9MlRl-XPwnEmWaDII3g-f8","q":"u9v4IOEsb4l2Y3eWKE2bwJh5fJRR4vivaYA7U-1-OpvDwB3A48Rey9IL1ucXqE5G1Du8BtijPm5oSAar5uzrjtg1bZ9gevif6DnBGaIRE7LnSrUsTPfZwzntJ1rTaGiVe_pAdnTKXXaH6DxygXxH4wvGgA44V3TTfBXQUcjzdEM","qi":"lDBnSPKkRnYqQvbqVD1LxzqBPEeqEA3GyCqMj6fIZNgoEaBSLi0TSsUyGZ5mahX3KO35vKAZa5jvGjhvUGUiXycq8KvRZdeGK45vJdwZT2TiXiDwo9IQgJcbFMpxaB9DhjX2x0yqxgUY5ca75jLqbMuKBKBN0PVqIr9jlHkR8_s","use":"sig","kid":"6823046760c5d460","alg":"RS256"}]}
--- a/docker-compose/deploy/.env.zh-CN.example
+++ b/docker-compose/deploy/.env.zh-CN.example
@@ -16,23 +16,25 @@
 # ===================
 # 如没有特殊需要不用更改
 LOBE_PORT=3210
-RUSTFS_PORT=9000
 APP_URL=http://localhost:3210
+# 内部应用URL是可选的，用于服务器内部调用
+# 如果没有设置，默认使用 APP_URL
+# INTERNAL_APP_URL=http://localhost:3210

 # 密钥配置（由 setup.sh 自动生成）
 KEY_VAULTS_SECRET=YOUR_KEY_VAULTS_SECRET
 AUTH_SECRET=YOUR_AUTH_SECRET

-# Postgres 相关，也即 DB 必须的环境变量
+# PostgreSQL 配置
 LOBE_DB_NAME=lobechat
 POSTGRES_PASSWORD=uWNZugjBqixf8dxC

 # RustFS S3 配置
+S3_ENDPOINT=http://localhost:9000
+RUSTFS_PORT=9000
+RUSTFS_ADMIN_PORT=9001
 RUSTFS_ACCESS_KEY=admin
 RUSTFS_SECRET_KEY=YOUR_RUSTFS_PASSWORD
-
-# 在下方配置 rustfs 中添加的桶
-S3_ENDPOINT=http://localhost:9000
 RUSTFS_LOBE_BUCKET=lobe

 JWKS_KEY={"keys":[{"d":"PVoFyqyrGstB8wU52S7gqqQQdZLtin_thcEM0nrNtqp9U-NlKLlhgEcWp5t89ycgvhsAzmrRbezGj4JBTr3jn7eWdwQpPJNYiipnsgeJn0pwsB0H2dMqtavxinoPVXkMTOuGHMTFhhyguFBw2JbIL0PTQUcUlXjv40OoJpYHZeggSxgfV-TuxjwW8Ll4-n84M5IOi6A53RvioE-Hm1iyIc2XLBCfyOu-SbAQYi8HzrA64kCxobAB0peLQMiAzfZmwPKiGOhnhKrAlYmG02qFnbUYiJu_-AXwsAyGv9S9i6dwK7QXaGGWYyis8LlPpd_JmPrBnrWomwDlI045NUMWZQ","dp":"OSXI2NBBZl2r0Dpf4-1z44A_jC5lOyXtJhXQYnSXy5eIuxTJcEtkUYagGEwnREO4Q3t-4J-lT_6Y71M1ZlgKG1upwfw1O4aE3vGpHOik9iZYYCjA8fe5uBfOpX1ELmOtHNoHRhMtyjuPxSFXLlSp3bgcF1f3F40ClukdvXCx0Mc","dq":"m6hNdfj-F8E_7nUlX2nG95OffkFrhHTo67ML9aPgpvFwBlzg-hk5LwtxMfUzngqWF78TMl0JDm7vS1bz0xlWqXqu8pFPoTUnUoWgYfvuyHLBwR5TgccQkfoKbkSMzYNy8VJPXZeyIjVXsW98tZvj-NZF-M9Pke_EWJm-jjXCu_8","e":"AQAB","kty":"RSA","n":"piffosMS0HOSgsSr_zQkXYaQt1kOCD73VR0b2XJD6UdQCKPbnBOzTIuA_xowX61QVsl5pCZLTw8ERC3r2Nlxj5Rp_H6RuOT7ioUqlbnxSGnfuAn8dFupY3A-sf9HVDOvtJdlS-nO9yA4wWU-A50zZ1Mf0pPZlUZE6dUQfsJFi5yXaNAybyk3U4VpMO_SXAilWEHVhiO0F0ccpJMCkT47AeXmYH9MlWwIGcay0UiAsdrs8J-q1arZ7Mbq0oxHmUXJG0vwRvAL8KnCEi8cJ3e2kKCRcr-BQCujsHUyUl6f_ATwSVuTHdAR1IzIcW37v27h3WQK_v0ffQM1NstamDX5vQ","p":"4myVm2M5cZGvVXsOmWUTUG87VC1GlQcL5tmMNSGSpQCL8yWZ1vANkmCxSMptrKB4dU9DAB3On6_oMhW1pJ3uYNGSW49BcmJoLkiWKeg5zWFnKPQNuThQmY1sCCubtKhBQgaYUr7TVzN9smrDV3zCu9MlRl-XPwnEmWaDII3g-f8","q":"u9v4IOEsb4l2Y3eWKE2bwJh5fJRR4vivaYA7U-1-OpvDwB3A48Rey9IL1ucXqE5G1Du8BtijPm5oSAar5uzrjtg1bZ9gevif6DnBGaIRE7LnSrUsTPfZwzntJ1rTaGiVe_pAdnTKXXaH6DxygXxH4wvGgA44V3TTfBXQUcjzdEM","qi":"lDBnSPKkRnYqQvbqVD1LxzqBPEeqEA3GyCqMj6fIZNgoEaBSLi0TSsUyGZ5mahX3KO35vKAZa5jvGjhvUGUiXycq8KvRZdeGK45vJdwZT2TiXiDwo9IQgJcbFMpxaB9DhjX2x0yqxgUY5ca75jLqbMuKBKBN0PVqIr9jlHkR8_s","use":"sig","kid":"6823046760c5d460","alg":"RS256"}]}
--- a/docker-compose/deploy/docker-compose.yml
+++ b/docker-compose/deploy/docker-compose.yml
@@ -1,20 +1,47 @@
 name: lobehub
 services:
-  network-service:
-    image: alpine
-    container_name: lobe-network
-    restart: always
+  lobe:
+    image: lobehub/lobehub
+    container_name: lobehub
    ports:
-      - '${RUSTFS_PORT}:9000' # RustFS API
-      - '9001:9001' # RustFS Console
-      - '${LOBE_PORT}:3210' # LobeChat
-    command: tail -f /dev/null
+      - '${LOBE_PORT}:3210'
+    depends_on:
+      postgresql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      rustfs:
+        condition: service_healthy
+      rustfs-init:
+        condition: service_completed_successfully
+    environment:
+      - 'KEY_VAULTS_SECRET=${KEY_VAULTS_SECRET}'
+      - 'AUTH_SECRET=${AUTH_SECRET}'
+      - 'DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgresql:5432/${LOBE_DB_NAME}'
+      - 'S3_ENDPOINT=${S3_ENDPOINT}'
+      - 'S3_BUCKET=${RUSTFS_LOBE_BUCKET}'
+      - 'S3_ENABLE_PATH_STYLE=1'
+      - 'S3_ACCESS_KEY=${RUSTFS_ACCESS_KEY}'
+      - 'S3_ACCESS_KEY_ID=${RUSTFS_ACCESS_KEY}'
+      - 'S3_SECRET_ACCESS_KEY=${RUSTFS_SECRET_KEY}'
+      - 'LLM_VISION_IMAGE_USE_BASE64=1'
+      - 'S3_SET_ACL=0'
+      - 'SEARXNG_URL=http://searxng:8080'
+      - 'REDIS_URL=redis://redis:6379'
+      - 'REDIS_PREFIX=lobechat'
+      - 'REDIS_TLS=0'
+    env_file:
+      - .env
+    restart: always
    networks:
      - lobe-network

  postgresql:
    image: paradedb/paradedb:latest-pg17
    container_name: lobe-postgres
+    # Optional: Remove or change these ports if:
+    # - You don't need external database access
+    # - The ports conflict with other services on your host
    ports:
      - '5432:5432'
    volumes:
@@ -34,6 +61,9 @@ services:
  redis:
    image: redis:7-alpine
    container_name: lobe-redis
+    # Optional: Remove or change these ports if:
+    # - You don't need external access
+    # - The ports conflict with other services on your host
    ports:
      - '6379:6379'
    command: redis-server --save 60 1000 --appendonly yes
@@ -51,13 +81,20 @@ services:
  rustfs:
    image: rustfs/rustfs:latest
    container_name: lobe-rustfs
-    network_mode: 'service:network-service'
+    ports:
+      - '${RUSTFS_PORT}:9000'
+      - '${RUSTFS_ADMIN_PORT}:9001'
+    # Optional: Remove or change RUSTFS_ADMIN_PORT if:
+    # - You don't need external access to rustfs control panel
+    # - The ports conflict with other services on your host
+    # - RUSTFS_PORT is necessary only if you need to upload images to conversations. (avatar uploads are not affected)
+    # - Uploading images to conversations requires a browser-accessible S3_ENDPOINT.
    environment:
      - RUSTFS_CONSOLE_ENABLE=true
      - RUSTFS_ACCESS_KEY=${RUSTFS_ACCESS_KEY}
      - RUSTFS_SECRET_KEY=${RUSTFS_SECRET_KEY}
    volumes:
-      - rustfs-data:/data
+      - 'rustfs-data:/data'
    healthcheck:
      test: ['CMD-SHELL', 'wget -qO- http://localhost:9000/health >/dev/null 2>&1 || exit 1']
      interval: 5s
@@ -65,6 +102,8 @@ services:
      retries: 30
    command:
      ['--access-key', '${RUSTFS_ACCESS_KEY}', '--secret-key', '${RUSTFS_SECRET_KEY}', '/data']
+    networks:
+      - lobe-network

  rustfs-init:
    image: minio/mc:latest
@@ -75,7 +114,7 @@ services:
    volumes:
      - ./bucket.config.json:/bucket.config.json:ro
    entrypoint: /bin/sh
-    command: -c ' set -eux; echo "S3_ACCESS_KEY=${RUSTFS_ACCESS_KEY}, S3_SECRET_KEY=${RUSTFS_SECRET_KEY}"; mc --version; mc alias set rustfs "http://network-service:9000" "${RUSTFS_ACCESS_KEY}" "${RUSTFS_SECRET_KEY}"; mc ls rustfs || true; mc mb "rustfs/lobe" --ignore-existing; mc admin info rustfs || true; mc anonymous set-json "/bucket.config.json" "rustfs/lobe"; '
+    command: -c ' set -eux; echo "S3_ACCESS_KEY=${RUSTFS_ACCESS_KEY}, S3_SECRET_KEY=${RUSTFS_SECRET_KEY}"; mc --version; mc alias set rustfs "http://rustfs:9000" "${RUSTFS_ACCESS_KEY}" "${RUSTFS_SECRET_KEY}"; mc ls rustfs || true; mc mb "rustfs/lobe" --ignore-existing; mc admin info rustfs || true; mc anonymous set-json "/bucket.config.json" "rustfs/lobe"; '
    restart: 'no'
    networks:
      - lobe-network
@@ -93,48 +132,12 @@ services:
    env_file:
      - .env

-  lobe:
-    image: lobehub/lobehub
-    container_name: lobehub
-    network_mode: 'service:network-service'
-    depends_on:
-      postgresql:
-        condition: service_healthy
-      network-service:
-        condition: service_started
-      rustfs:
-        condition: service_healthy
-      rustfs-init:
-        condition: service_completed_successfully
-      redis:
-        condition: service_healthy
-    environment:
-      - 'KEY_VAULTS_SECRET=${KEY_VAULTS_SECRET}'
-      - 'AUTH_SECRET=${AUTH_SECRET}'
-      - 'DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgresql:5432/${LOBE_DB_NAME}'
-      - 'S3_BUCKET=${RUSTFS_LOBE_BUCKET}'
-      - 'S3_ENABLE_PATH_STYLE=1'
-      - 'S3_ACCESS_KEY=${RUSTFS_ACCESS_KEY}'
-      - 'S3_ACCESS_KEY_ID=${RUSTFS_ACCESS_KEY}'
-      - 'S3_SECRET_ACCESS_KEY=${RUSTFS_SECRET_KEY}'
-      - 'LLM_VISION_IMAGE_USE_BASE64=1'
-      - 'S3_SET_ACL=0'
-      - 'SEARXNG_URL=http://searxng:8080'
-      - 'REDIS_URL=redis://redis:6379'
-      - 'REDIS_PREFIX=lobechat'
-      - 'REDIS_TLS=0'
-    env_file:
-      - .env
-    restart: always
+networks:
+  lobe-network:
+    driver: bridge

 volumes:
-  data:
-    driver: local
  redis_data:
    driver: local
  rustfs-data:
    driver: local
-
-networks:
-  lobe-network:
-    driver: bridge
--- a/docs/self-hosting/platform/docker-compose.mdx
+++ b/docs/self-hosting/platform/docker-compose.mdx
@@ -186,6 +186,18 @@ The script supports the following deployment modes; please choose the appropriat
  - Choose the access protocol: `http` or `https`
  - Regenerate secure keys: We highly recommend regenerating the secure keys; if you lack the key generation library required by the script, we suggest referring to the [Custom Deployment](#custom-deployment) section for key modifications.

+  <Callout type="tip">
+    **Single Domain Deployment**
+    If you only have one domain, you can distinguish services by different ports:
+    - Domain setup for the LobeHub service: `lobe.example.com:${PORT1}`
+    - Domain setup for the S3 service: `lobe.example.com:${PORT2}`
+    You need to configure forwarding rules for each port in the reverse proxy.
+
+    **Port Mode vs Domain Mode:**
+    - Port Mode: The script automatically uses default ports (3210/9000/9001)
+    - Domain Mode: You can customize ports (via reverse proxy configuration)
+  </Callout>
+
  <Callout type="warning">
    The following issues may impede access to your service:

@@ -250,11 +262,6 @@ curl -O https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/
 mv .env.example .env
 ```

-<Callout type="info">
-  This section does not cover all complete variables; remaining variables can be referenced in
-  [Deploying with the Server Database](/en/docs/self-hosting/server-database).
-</Callout>
-
 ### Prerequisites

 Generally, to fully run the LobeHub database version, you will need at least the following three services:
@@ -280,6 +287,10 @@ Now, we will introduce the necessary configurations for running these services:

 LobeHub needs to provide a public access URL for object files for the LLM service provider, so you need to configure the S3 Endpoint:

+<Callout type="tip">
+  Using `S3_ENDPOINT=http://rustfs:9000` directly will prevent conversation image uploads from working (browser cannot resolve container names), but avatar uploads are not affected.
+</Callout>
+
 ```env
 S3_ENDPOINT=https://s3.example.com
 ```
@@ -345,7 +356,7 @@ If `INTERNAL_APP_URL` is not set, it defaults to `APP_URL`.
 - `http://127.0.0.1:3210` - Alternative localhost address

 <Callout type="tip">
-  For Docker Compose deployments with `network_mode: 'service:network-service'`, use `http://localhost:3210` as the `INTERNAL_APP_URL`.
+  For Docker Compose deployments, we recommend using `http://lobe:3210` as the `INTERNAL_APP_URL` (using service name for container-to-container communication).
 </Callout>

 ## Reverse Proxy Configuration
--- a/docs/self-hosting/platform/docker-compose.zh-CN.mdx
+++ b/docs/self-hosting/platform/docker-compose.zh-CN.mdx
@@ -183,6 +183,17 @@ bash <(curl -fsSL https://lobe.li/setup.sh) -l zh_CN
  - 选择访问协议：`http` 或 `https`
  - 安全密钥重新生成：我们强烈建议你重新生成安全密钥，如果你缺少脚本所需的密钥生成库，我们建议你参考 [自定义部署](#自定义部署) 章节对密钥进行修改。

+  <Callout type="tip">
+    **单域名部署方案**
+    如果只有一个域名，可以通过不同端口区分服务：
+    - LobeHub 服务的域名设置：`lobe.example.com:${PORT1}`
+    - S3 服务的域名设置：`lobe.example.com:${PORT2}`
+    需在反向代理中配置对应端口的转发规则。
+    **端口模式 vs 域名模式：**
+    - 端口模式：一键安装脚本自动使用默认端口（3210/9000/9001）
+    - 域名模式：可自定义端口（通过反向代理配置）
+  </Callout>
+
  <Callout type="warning">
    以下问题可能导致你的服务无法正常访问：

@@ -247,11 +258,6 @@ curl -O https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/
 mv .env.zh-CN.example .env
 ```

-<Callout type="info">
-  本章节并不包含所有完整变量，剩余的变量可以查阅
-  [使用服务端数据库部署](/zh/docs/self-hosting/server-database) 。
-</Callout>
-
 ### 预备知识

 一般来讲，想要完整的运行 LobeHub，你需要至少拥有如下三个服务：
@@ -276,6 +282,10 @@ mv .env.zh-CN.example .env

 LobeHub 需要为 LLM 服务提供商提供文件对象的公网访问地址，因此你需要配置 S3 的 Endpoint：

+<Callout type="warning">
+  直接使用 `S3_ENDPOINT=http://rustfs:9000` 会导致对话内上传图片不可用（浏览器无法直接访问容器内网），但是头像上传不受影响
+</Callout>
+
 ```env
 S3_ENDPOINT=https://s3.example.com
 ```
@@ -341,7 +351,7 @@ environment:
 - `http://127.0.0.1:3210` - 备用本地主机地址

 <Callout type="tip">
-  对于使用 `network_mode: 'service:network-service'` 的 Docker Compose 部署，请使用 `http://localhost:3210` 作为 `INTERNAL_APP_URL`。
+  对于 Docker Compose 部署，推荐使用 `http://lobe:3210` 作为 `INTERNAL_APP_URL`（使用服务名称进行容器间通信）。
 </Callout>

 ## 反向代理配置