feat: implement runtime configuration injection for VITE_API_BASE

Rabithua · Rabithua · commit 38437b1594f8 · 2025-11-15T20:02:24.000+08:00
- Add docker-entrypoint.sh to inject VITE_API_BASE at container startup
- Update Dockerfile to use entrypoint script for runtime configuration
- Modify api.ts to support runtime config with fallback mechanism
- Add placeholder in index.html for configuration injection
- Update docker-compose.yml to pass VITE_API_BASE environment variable
- Support multiple injection strategies (placeholder replacement, script update, script insertion)
- Ensure configuration injection failures don't prevent container startup
diff --git a/.github/workflows/develop-deploy.yml b/.github/workflows/develop-deploy.yml
@@ -55,8 +55,6 @@ jobs:
           context: ./web
           file: ./web/Dockerfile
           push: true
-          build-args: |
-            VITE_API_BASE=${{ secrets.VITE_API_BASE || 'http://localhost:3000' }}
           tags: |
             ${{ secrets.DOCKERHUB_USERNAME }}/rote-frontend:latest-dev
             ${{ secrets.DOCKERHUB_USERNAME }}/rote-frontend:develop
diff --git a/.github/workflows/release-deploy.yml b/.github/workflows/release-deploy.yml
@@ -56,8 +56,6 @@ jobs:
           context: ./web
           file: ./web/Dockerfile
           push: true
-          build-args: |
-            VITE_API_BASE=${{ secrets.VITE_API_BASE || 'http://localhost:3000' }}
           tags: |
             ${{ secrets.DOCKERHUB_USERNAME }}/rote-frontend:latest
             ${{ secrets.DOCKERHUB_USERNAME }}/rote-frontend:${{ github.event.release.tag_name || github.ref_name || 'main' }}
diff --git a/README.md b/README.md
@@ -8,8 +8,30 @@
 
 ## Deploy
 
-To Be Continue...
+### 快速开始
 
+#### 方式一：使用 Docker Hub 镜像（推荐）
+
+```bash
+# 使用最新版本（默认配置文件）
+docker-compose up -d
+
+# 使用特定版本
+IMAGE_TAG=v1.0.0 docker-compose up -d
+```
+
+#### 方式二：本地构建
+
+```bash
+# 从源码构建并启动
+# VITE_API_BASE 在构建时注入到前端代码中（可选，默认 http://localhost:3000）
+VITE_API_BASE=http://localhost:3000 docker-compose -f docker-compose.build.yml up -d --build
+```
+
+### 详细说明
+
+更多部署选项和配置说明，请查看 [Docker Compose 使用指南](doc/userguide/DOCKER-COMPOSE-GUIDE.md)。
 
 ## Technology stack
+
 ![Frame 1](https://github.com/Rabithua/Rote/assets/34543831/fc00f797-82bc-47fe-8c75-36ea0b1f6f76)
diff --git a/docker-compose.build.yml b/docker-compose.build.yml
@@ -0,0 +1,40 @@
+services:
+  rote-backend:
+    build:
+      context: ./server
+    environment:
+      # 基础配置 - 必需
+      - POSTGRESQL_URL=postgresql://prisma:${POSTGRES_PASSWORD:-rote_password_123}@postgres:5432/rote
+    ports:
+      - "3000:3000"
+    depends_on:
+      - postgres
+    restart: unless-stopped
+
+  rote-frontend:
+    build:
+      context: ./web
+      args:
+        # 构建时传递 VITE_API_BASE，会在构建时注入到前端代码中
+        # 如果未设置，将使用默认值 http://localhost:3000
+        - VITE_API_BASE=${VITE_API_BASE:-http://localhost:3000}
+    ports:
+      - "3001:3001"
+    depends_on:
+      - rote-backend
+    restart: unless-stopped
+  postgres:
+    image: postgres:17
+    container_name: rote-postgres
+    restart: unless-stopped
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: prisma
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-rote_password_123}
+      POSTGRES_DB: rote
+    volumes:
+      - rote-postgres-data:/var/lib/postgresql/data
+
+volumes:
+  rote-postgres-data:
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,27 +1,57 @@
+# Docker Compose configuration using pre-built images from Docker Hub
+# Usage: docker-compose up -d
+#
+# To use a specific version, set IMAGE_TAG environment variable:
+# IMAGE_TAG=v1.0.0 docker-compose up -d
+#
+# Available tags:
+# - latest: Latest stable release
+# - main: Latest from main branch
+# - develop: Latest from develop branch
+# - v1.0.0: Specific version (if released)
+
 services:
   rote-backend:
-    build:
-      context: ./server
+    image: rabithua/rote-backend:${IMAGE_TAG:-latest}
+    container_name: rote-backend
     environment:
       # 基础配置 - 必需
       - POSTGRESQL_URL=postgresql://prisma:${POSTGRES_PASSWORD:-rote_password_123}@postgres:5432/rote
     ports:
       - "3000:3000"
     depends_on:
-      - postgres
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          'node -e "require(''http'').get(''http://localhost:3000/v2/api/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)}).on(''error'', () => process.exit(1))" || exit 1',
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
     restart: unless-stopped
 
   rote-frontend:
-    build:
-      context: ./web
-      args:
-        # 构建时传递 VITE_API_BASE，如果未设置则使用默认值
-        - VITE_API_BASE=${VITE_API_BASE:-http://localhost:3000}
+    image: rabithua/rote-frontend:${IMAGE_TAG:-latest}
+    container_name: rote-frontend
     ports:
       - "3001:3001"
     depends_on:
-      - rote-backend
+      rote-backend:
+        condition: service_healthy
+    environment:
+      - VITE_API_BASE=${VITE_API_BASE:-http://localhost:3000}
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:3001 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
     restart: unless-stopped
+
   postgres:
     image: postgres:17
     container_name: rote-postgres
@@ -34,6 +64,12 @@ services:
       POSTGRES_DB: rote
     volumes:
       - rote-postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U prisma -d rote"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
 
 volumes:
   rote-postgres-data:
diff --git a/web/Dockerfile b/web/Dockerfile
@@ -23,7 +23,7 @@ RUN rm -rf node_modules && bun install --force
 COPY . .
 
 # 构建前端静态文件
-# 使用 ARG 接收构建参数，然后设置为环境变量供构建时使用
+# VITE_API_BASE 在构建时通过 ARG 传入并注入到代码中
 ARG VITE_API_BASE=http://localhost:3000
 ENV VITE_API_BASE=${VITE_API_BASE}
 RUN bun run build
@@ -47,6 +47,11 @@ COPY --from=builder /app/vite.config.ts ./
 # 安装所有依赖（vite preview 需要 vite，它在 devDependencies 中）
 RUN bun install
 
-# 直接用 Vite 预览模式启动（适合开发/预览环境）
+# 从构建上下文复制启动脚本并设置执行权限
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# 使用启动脚本作为入口点，在启动时注入环境变量
 EXPOSE 3001
+ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["bun", "run", "preview"]
diff --git a/web/docker-entrypoint.sh b/web/docker-entrypoint.sh
@@ -0,0 +1,68 @@
+#!/bin/sh
+# Docker 容器启动脚本
+# 在容器启动时注入环境变量到 HTML 文件中
+
+# 默认值
+VITE_API_BASE="${VITE_API_BASE:-http://localhost:3000}"
+
+# 替换 HTML 中的占位符（配置注入失败不应阻止容器启动）
+if [ -f /app/dist/index.html ]; then
+  # 转义 sed 替换字符串中的特殊字符（& 和 \）
+  # 使用 | 作为分隔符避免与 URL 中的 / 冲突
+  # 先转义 \，再转义 &
+  ESCAPED_API_BASE=$(echo "${VITE_API_BASE}" | sed 's/\\/\\\\/g; s/&/\\&/g' 2>/dev/null || echo "${VITE_API_BASE}")
+  
+  # 转义 JSON 字符串中的特殊字符（用于 JavaScript 代码）
+  JSON_ESCAPED_API_BASE=$(echo "${VITE_API_BASE}" | sed 's/\\/\\\\/g; s/"/\\"/g' 2>/dev/null || echo "${VITE_API_BASE}")
+  
+  # 首先尝试替换占位符（如果存在）
+  if grep -q "__VITE_API_BASE_PLACEHOLDER__" /app/dist/index.html 2>/dev/null; then
+    # 使用 sed 替换占位符（Alpine/busybox 兼容）
+    if sed -i "s|__VITE_API_BASE_PLACEHOLDER__|${ESCAPED_API_BASE}|g" /app/dist/index.html 2>/dev/null; then
+      echo "✓ 已注入 VITE_API_BASE: ${VITE_API_BASE}"
+    elif sed "s|__VITE_API_BASE_PLACEHOLDER__|${ESCAPED_API_BASE}|g" /app/dist/index.html > /tmp/index.html.tmp 2>/dev/null && \
+         mv /tmp/index.html.tmp /app/dist/index.html 2>/dev/null; then
+      echo "✓ 已注入 VITE_API_BASE: ${VITE_API_BASE}"
+    else
+      echo "⚠ 警告: 占位符替换失败，尝试插入配置脚本"
+      # 如果替换失败，尝试在 </head> 前插入配置脚本
+      CONFIG_SCRIPT="<script>window.__ROTE_CONFIG__=window.__ROTE_CONFIG__||{};window.__ROTE_CONFIG__.VITE_API_BASE=\"${JSON_ESCAPED_API_BASE}\";</script>"
+      if sed -i "s|</head>|${CONFIG_SCRIPT}</head>|" /app/dist/index.html 2>/dev/null || \
+         sed "s|</head>|${CONFIG_SCRIPT}</head>|" /app/dist/index.html > /tmp/index.html.tmp 2>/dev/null && \
+         mv /tmp/index.html.tmp /app/dist/index.html 2>/dev/null; then
+        echo "✓ 已插入配置脚本，VITE_API_BASE: ${VITE_API_BASE}"
+      else
+        echo "⚠ 警告: 配置注入失败，将使用构建时配置或默认值"
+      fi
+    fi
+  else
+    # 如果占位符不存在，检查是否已有配置脚本
+    if grep -q "__ROTE_CONFIG__" /app/dist/index.html 2>/dev/null; then
+      # 如果已有配置脚本，尝试更新它
+      if sed -i "s|\"VITE_API_BASE\":\"[^\"]*\"|\"VITE_API_BASE\":\"${JSON_ESCAPED_API_BASE}\"|g" /app/dist/index.html 2>/dev/null || \
+         sed "s|\"VITE_API_BASE\":\"[^\"]*\"|\"VITE_API_BASE\":\"${JSON_ESCAPED_API_BASE}\"|g" /app/dist/index.html > /tmp/index.html.tmp 2>/dev/null && \
+         mv /tmp/index.html.tmp /app/dist/index.html 2>/dev/null; then
+        echo "✓ 已更新配置脚本，VITE_API_BASE: ${VITE_API_BASE}"
+      else
+        echo "⚠ 警告: 配置脚本更新失败，将使用构建时配置或默认值"
+      fi
+    else
+      # 如果既没有占位符也没有配置脚本，在 </head> 前插入配置脚本
+      CONFIG_SCRIPT="<script>window.__ROTE_CONFIG__=window.__ROTE_CONFIG__||{};window.__ROTE_CONFIG__.VITE_API_BASE=\"${JSON_ESCAPED_API_BASE}\";</script>"
+      if sed -i "s|</head>|${CONFIG_SCRIPT}</head>|" /app/dist/index.html 2>/dev/null || \
+         sed "s|</head>|${CONFIG_SCRIPT}</head>|" /app/dist/index.html > /tmp/index.html.tmp 2>/dev/null && \
+         mv /tmp/index.html.tmp /app/dist/index.html 2>/dev/null; then
+        echo "✓ 已插入配置脚本，VITE_API_BASE: ${VITE_API_BASE}"
+      else
+        echo "⚠ 警告: 配置注入失败，将使用构建时配置或默认值"
+      fi
+    fi
+  fi
+else
+  echo "⚠ 警告: /app/dist/index.html 不存在，跳过配置注入"
+fi
+
+# 执行原始命令（使用 set -e 确保命令失败时容器退出）
+set -e
+exec "$@"
+
diff --git a/web/index.html b/web/index.html
@@ -33,6 +33,12 @@
     <script>
       iosPWASplash('logo.png', '#ffffff');
     </script>
+    <!-- 运行时配置注入：容器启动脚本会替换此处的占位符 -->
+    <script>
+      window.__ROTE_CONFIG__ = window.__ROTE_CONFIG__ || {
+        VITE_API_BASE: '__VITE_API_BASE_PLACEHOLDER__',
+      };
+    </script>
     <!-- Umami -->
     <script
       defer
diff --git a/web/src/utils/api.ts b/web/src/utils/api.ts
@@ -6,34 +6,41 @@ const API_PATH = '/v2/api';
 
 /**
  * 获取 API 基础 URL
- * 处理构建时可能为 undefined 的情况，确保始终返回有效的 URL
+ * 优先级：运行时配置 > 构建时配置 > 默认值
+ * 支持通过 window.__ROTE_CONFIG__ 在运行时注入配置
  */
 const getApiPoint = (): string => {
-  // Vite 使用 import.meta.env 访问环境变量（以 VITE_ 开头的变量会自动暴露）
-  const apiBase = import.meta.env.VITE_API_BASE;
   const defaultValue = 'http://localhost:3000';
 
-  // 如果 VITE_API_BASE 未设置或无效，使用默认值
-  if (!apiBase) {
-    if (import.meta.env.DEV) {
-      // eslint-disable-next-line no-console
-      console.warn('[api.ts] VITE_API_BASE is not set, using default:', defaultValue);
+  // 优先读取运行时配置（从 window 对象，由容器启动脚本注入）
+  const runtimeConfig = (window as any).__ROTE_CONFIG__;
+  if (runtimeConfig?.VITE_API_BASE) {
+    const runtimeApiBase = String(runtimeConfig.VITE_API_BASE).trim();
+    if (
+      runtimeApiBase &&
+      runtimeApiBase !== 'undefined' &&
+      runtimeApiBase !== 'null' &&
+      runtimeApiBase !== ''
+    ) {
+      return runtimeApiBase;
     }
-    return defaultValue;
   }
 
-  // 确保 apiBase 是字符串类型并验证有效性
-  const apiBaseStr = String(apiBase).trim();
-
-  if (apiBaseStr === 'undefined' || apiBaseStr === 'null' || apiBaseStr === '') {
-    if (import.meta.env.DEV) {
-      // eslint-disable-next-line no-console
-      console.warn('[api.ts] VITE_API_BASE is invalid, using default:', defaultValue);
+  // 其次读取构建时配置（Vite 环境变量）
+  const apiBase = import.meta.env.VITE_API_BASE;
+  if (apiBase) {
+    const apiBaseStr = String(apiBase).trim();
+    if (apiBaseStr !== 'undefined' && apiBaseStr !== 'null' && apiBaseStr !== '') {
+      return apiBaseStr;
     }
-    return defaultValue;
   }
 
-  return apiBaseStr;
+  // 如果都未设置或无效，使用默认值
+  if (import.meta.env.DEV) {
+    // eslint-disable-next-line no-console
+    console.warn('[api.ts] VITE_API_BASE is not set, using default:', defaultValue);
+  }
+  return defaultValue;
 };
 
 export const API_POINT = getApiPoint();
