feat: 更新环境变量配置，完善 Gitea CI/CD 文档

.env.example

@@ -1,29 +1,80 @@
-# Nuxt / SEO
+# Local .env uses KEY=value for every item.
+# Gitea uses two places:
+# - Variables: non-sensitive values, such as ports, URLs, names, limits.
+# - Secrets: sensitive values, such as database credentials and tokens.
+
+# Required / Gitea Secrets / Local .env
+# Nuxt SEO/OG image secret.
 NUXT_OG_IMAGE_SECRET=change-me
 
-# Database
+# Required / Gitea Secrets / Local .env
+# MariaDB connection string. Keep it secret because it contains DB credentials.
 DATABASE_URL=mysql://user:password@localhost:3306/aiartstudio?connection_limit=5&pool_timeout=30&connect_timeout=10
 
-# NewAPI upstream
+# Required / Gitea Variables / Local .env
+# Host port exposed on the deployment machine. Used by CI only, not by the app.
+HOST_PORT=3000
+
+# Required / Gitea Variables / Local .env
+# NewAPI upstream base URL.
 NEWAPI_BASE_URL=https://api.example.com
+
+# Required / Gitea Variables / Local .env
+# Image generation model name.
 IMAGE_GENERATION_MODEL=gpt-image-2
+
+# Required / Gitea Variables / Local .env
+# Token name maintained for this site in NewAPI.
 NEWAPI_TOKEN_NAME=AIArtStudio
 
-# Lsky image hosting
+# Required / Gitea Variables / Local .env
+# Lsky image hosting base URL.
 LSKY_BASE_URL=https://lsky.example.com
+
+# Required / Gitea Secrets / Local .env
+# Lsky Bearer token. Keep it secret.
 LSKY_TOKEN=change-me
+
+# Required / Gitea Variables / Local .env
+# Lsky storage strategy ID.
 LSKY_STORAGE_ID=1
 
-# Image generation runtime tuning
+# Optional / Gitea Variables / Local .env
+# Max images per generation request. Defaults to 3 if missing or invalid.
 IMAGE_GENERATION_MAX_BATCH_SIZE=3
+
+# Optional / Gitea Variables / Local .env
+# Max retries when a generated image URL cannot be parsed. Defaults to 3.
 IMAGE_GENERATION_MAX_RETRIES=3
+
+# Optional / Gitea Variables / Local .env
+# Max bytes for one SSE data line. Defaults to 1048576.
 IMAGE_STREAM_MAX_SSE_LINE_BYTES=1048576
 
-# Image archive runtime tuning
+# Optional / Gitea Variables / Local .env
+# Max bytes for one archived image. Defaults to 20971520.
 IMAGE_ARCHIVE_MAX_BYTES=20971520
+
+# Optional / Gitea Variables / Local .env
+# Download/upload timeout in milliseconds. Defaults to 60000.
 IMAGE_ARCHIVE_TIMEOUT_MS=60000
+
+# Optional / Gitea Variables / Local .env
+# Archive worker concurrency per process. Defaults to 2.
 IMAGE_ARCHIVE_CONCURRENCY=2
+
+# Optional / Gitea Variables / Local .env
+# Max archive attempts per image. Defaults to 3.
 IMAGE_ARCHIVE_MAX_ATTEMPTS=3
+
+# Optional / Gitea Variables / Local .env
+# Lock TTL for RUNNING archive tasks in milliseconds. Defaults to 600000.
 IMAGE_ARCHIVE_LOCK_TTL_MS=600000
+
+# Optional / Gitea Variables / Local .env
+# Poll interval for an empty archive queue in milliseconds. Defaults to 15000.
 IMAGE_ARCHIVE_POLL_MS=15000
+
+# Optional / Gitea Variables / Local .env
+# Retry delays in milliseconds, comma-separated. Defaults to 30000,120000,600000.
 IMAGE_ARCHIVE_RETRY_DELAYS_MS=30000,120000,600000

.gitea/workflows/deploy.yml

@@ -18,14 +18,16 @@ jobs:
     steps:
       - name: Check runner
         env:
-          HOST_PORT: "${{ secrets.HOST_PORT }}"
+          # Required Gitea Variables
+          HOST_PORT: "${{ vars.HOST_PORT }}"
+          NEWAPI_BASE_URL: "${{ vars.NEWAPI_BASE_URL }}"
+          IMAGE_GENERATION_MODEL: "${{ vars.IMAGE_GENERATION_MODEL }}"
+          NEWAPI_TOKEN_NAME: "${{ vars.NEWAPI_TOKEN_NAME }}"
+          LSKY_BASE_URL: "${{ vars.LSKY_BASE_URL }}"
+          LSKY_STORAGE_ID: "${{ vars.LSKY_STORAGE_ID }}"
+          # Required Gitea Secrets
           DATABASE_URL: "${{ secrets.DATABASE_URL }}"
-          NEWAPI_BASE_URL: "${{ secrets.NEWAPI_BASE_URL }}"
-          IMAGE_GENERATION_MODEL: "${{ secrets.IMAGE_GENERATION_MODEL }}"
-          NEWAPI_TOKEN_NAME: "${{ secrets.NEWAPI_TOKEN_NAME }}"
-          LSKY_BASE_URL: "${{ secrets.LSKY_BASE_URL }}"
           LSKY_TOKEN: "${{ secrets.LSKY_TOKEN }}"
-          LSKY_STORAGE_ID: "${{ secrets.LSKY_STORAGE_ID }}"
           NUXT_OG_IMAGE_SECRET: "${{ secrets.NUXT_OG_IMAGE_SECRET }}"
         run: |
           set -eu
@@ -61,7 +63,7 @@ jobs:
           done
 
           if [ -n "$MISSING" ]; then
-            echo "Missing required secrets:$MISSING"
+            echo "Missing required Gitea variables/secrets:$MISSING"
             exit 1
           fi
 
@@ -104,25 +106,28 @@ jobs:
 
       - name: Deploy container
         env:
-          HOST_PORT: "${{ secrets.HOST_PORT }}"
+          # Required Gitea Variables
+          HOST_PORT: "${{ vars.HOST_PORT }}"
+          NEWAPI_BASE_URL: "${{ vars.NEWAPI_BASE_URL }}"
+          IMAGE_GENERATION_MODEL: "${{ vars.IMAGE_GENERATION_MODEL }}"
+          NEWAPI_TOKEN_NAME: "${{ vars.NEWAPI_TOKEN_NAME }}"
+          LSKY_BASE_URL: "${{ vars.LSKY_BASE_URL }}"
+          LSKY_STORAGE_ID: "${{ vars.LSKY_STORAGE_ID }}"
+          # Required Gitea Secrets
           DATABASE_URL: "${{ secrets.DATABASE_URL }}"
-          NEWAPI_BASE_URL: "${{ secrets.NEWAPI_BASE_URL }}"
-          IMAGE_GENERATION_MODEL: "${{ secrets.IMAGE_GENERATION_MODEL }}"
-          NEWAPI_TOKEN_NAME: "${{ secrets.NEWAPI_TOKEN_NAME }}"
-          LSKY_BASE_URL: "${{ secrets.LSKY_BASE_URL }}"
           LSKY_TOKEN: "${{ secrets.LSKY_TOKEN }}"
-          LSKY_STORAGE_ID: "${{ secrets.LSKY_STORAGE_ID }}"
           NUXT_OG_IMAGE_SECRET: "${{ secrets.NUXT_OG_IMAGE_SECRET }}"
-          IMAGE_GENERATION_MAX_BATCH_SIZE: "${{ secrets.IMAGE_GENERATION_MAX_BATCH_SIZE }}"
-          IMAGE_GENERATION_MAX_RETRIES: "${{ secrets.IMAGE_GENERATION_MAX_RETRIES }}"
-          IMAGE_STREAM_MAX_SSE_LINE_BYTES: "${{ secrets.IMAGE_STREAM_MAX_SSE_LINE_BYTES }}"
-          IMAGE_ARCHIVE_MAX_BYTES: "${{ secrets.IMAGE_ARCHIVE_MAX_BYTES }}"
-          IMAGE_ARCHIVE_TIMEOUT_MS: "${{ secrets.IMAGE_ARCHIVE_TIMEOUT_MS }}"
-          IMAGE_ARCHIVE_CONCURRENCY: "${{ secrets.IMAGE_ARCHIVE_CONCURRENCY }}"
-          IMAGE_ARCHIVE_MAX_ATTEMPTS: "${{ secrets.IMAGE_ARCHIVE_MAX_ATTEMPTS }}"
-          IMAGE_ARCHIVE_LOCK_TTL_MS: "${{ secrets.IMAGE_ARCHIVE_LOCK_TTL_MS }}"
-          IMAGE_ARCHIVE_POLL_MS: "${{ secrets.IMAGE_ARCHIVE_POLL_MS }}"
-          IMAGE_ARCHIVE_RETRY_DELAYS_MS: "${{ secrets.IMAGE_ARCHIVE_RETRY_DELAYS_MS }}"
+          # Optional Gitea Variables
+          IMAGE_GENERATION_MAX_BATCH_SIZE: "${{ vars.IMAGE_GENERATION_MAX_BATCH_SIZE }}"
+          IMAGE_GENERATION_MAX_RETRIES: "${{ vars.IMAGE_GENERATION_MAX_RETRIES }}"
+          IMAGE_STREAM_MAX_SSE_LINE_BYTES: "${{ vars.IMAGE_STREAM_MAX_SSE_LINE_BYTES }}"
+          IMAGE_ARCHIVE_MAX_BYTES: "${{ vars.IMAGE_ARCHIVE_MAX_BYTES }}"
+          IMAGE_ARCHIVE_TIMEOUT_MS: "${{ vars.IMAGE_ARCHIVE_TIMEOUT_MS }}"
+          IMAGE_ARCHIVE_CONCURRENCY: "${{ vars.IMAGE_ARCHIVE_CONCURRENCY }}"
+          IMAGE_ARCHIVE_MAX_ATTEMPTS: "${{ vars.IMAGE_ARCHIVE_MAX_ATTEMPTS }}"
+          IMAGE_ARCHIVE_LOCK_TTL_MS: "${{ vars.IMAGE_ARCHIVE_LOCK_TTL_MS }}"
+          IMAGE_ARCHIVE_POLL_MS: "${{ vars.IMAGE_ARCHIVE_POLL_MS }}"
+          IMAGE_ARCHIVE_RETRY_DELAYS_MS: "${{ vars.IMAGE_ARCHIVE_RETRY_DELAYS_MS }}"
         run: |
           set -eu
 

README.md

@@ -44,14 +44,13 @@ aiartstudio/                          # 项目根目录
 部署时由 CI/CD 注入真实环境变量，本地开发可参考 `.env.example` 创建 `.env`。
 `.env` 被 Git 忽略，不能提交真实密钥。
 
-必填配置：
+Gitea CI/CD 配置位置：
 
-- `DATABASE_URL`：MariaDB 连接串，Prisma MariaDB adapter 会从查询参数读取连接池配置。
-- `NEWAPI_BASE_URL`：NewAPI 上游根地址，例如 `https://api.example.com`。
-- `IMAGE_GENERATION_MODEL`：生图模型名，例如 `gpt-image-2`。
-- `NEWAPI_TOKEN_NAME`：当前站点在 NewAPI 中维护的 token 名称。
-- `LSKY_BASE_URL`、`LSKY_TOKEN`、`LSKY_STORAGE_ID`：Lsky 图床归档配置。
-- `NUXT_OG_IMAGE_SECRET`：Nuxt SEO/OG image 使用的 secret。
+- 必填 Secrets：`DATABASE_URL`、`LSKY_TOKEN`、`NUXT_OG_IMAGE_SECRET`。
+- 必填 Variables：`HOST_PORT`、`NEWAPI_BASE_URL`、`IMAGE_GENERATION_MODEL`、`NEWAPI_TOKEN_NAME`、`LSKY_BASE_URL`、`LSKY_STORAGE_ID`。
+- 可选 Variables：下方所有运行调参项；未设置或非法时使用代码默认值。
+
+本地 `.env` 不区分 Variables/Secrets，全部写成 `KEY=value`。其中 `DATABASE_URL`、`LSKY_TOKEN`、`NUXT_OG_IMAGE_SECRET` 属于敏感值，不要提交。
 
 可调配置未设置或非法时会使用代码默认值：