From 2dcb79065d15fef416c05849272f95475a13f459 Mon Sep 17 00:00:00 2001 From: tvon <125454309+t59688@users.noreply.github.com> Date: Thu, 16 Oct 2025 22:35:49 +0800 Subject: [PATCH] Revise .env.example with clearer instructions Updated the .env.example file with improved instructions and configuration options. --- .env.example | 166 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 107 insertions(+), 59 deletions(-) diff --git a/.env.example b/.env.example index 98ab88c..d293f14 100644 --- a/.env.example +++ b/.env.example @@ -1,94 +1,142 @@ -# ============================================ +# =================================================================== # Docker Compose 环境变量配置示例 -# ============================================ +# =================================================================== +# # 使用说明： -# 1. 复制此文件为 .env: cp .env.example .env -# 2. 修改以下配置项为您的实际值 -# 3. 根据数据库选择启动命令： -# - 默认 SQLite: docker compose up -d -# - 内置 MySQL: DB_PROVIDER=mysql docker compose --profile mysql up -d -# - 外部 MySQL: DB_PROVIDER=mysql docker compose up -d -# ============================================ +# 1. 将此文件复制为 .env 文件: `cp .env.example .env` +# 2. 根据您的实际需求，仔细检查并修改以下配置项。 +# 3. 使用默认的 SQLite 数据库快速启动，只需运行: +# docker compose up -d +# +# =================================================================== -# -------------------------------------------- -# 应用端口配置 -# -------------------------------------------- +# ------------------------------------------------------------------- +# A. 核心应用配置 +# ------------------------------------------------------------------- +# [必需] 应用对外暴露的网络端口 APP_PORT=8088 -# -------------------------------------------- -# FastAPI 基础配置 -# -------------------------------------------- -# SECRET_KEY 用于 JWT token 加密，必须设置为随机且复杂的字符串 +# [必需] 用于 JWT token 等安全功能的加密密钥。 +# 警告：为了生产环境的安全，请务必将其修改为一个长且随机的复杂字符串！ +# 您可以使用此命令生成: openssl rand -hex 32 SECRET_KEY=your-secret-key-change-me-to-random-string -ENVIRONMENT=production -DEBUG=false -# -------------------------------------------- -# 数据库配置 -# -------------------------------------------- -# mysql/sqlite 默认数据库类型；docker compose up -d 将以 SQLite 运行 -DB_PROVIDER=sqlite -# SQLite 数据存储映射（可选）：留空或移除即使用命名卷 sqlite-data -# 可设置为宿主机路径或其他卷名，例如：./storage 或 /data/arboris +# [可选] 应用环境，设置为 "development" 可以启用更详细的调试日志 +ENVIRONMENT=production + +# [可选] 是否开启调试模式，生产环境中应始终为 "false" +DEBUG=false +# [可选] 控制应用日志级别，可选值：CRITICAL/ERROR/WARNING/INFO/DEBUG/NOTSET +LOGGING_LEVEL=INFO + + +# ------------------------------------------------------------------- +# B. 数据库配置 +# ------------------------------------------------------------------- +# [必需] 选择数据库类型。可选值: "sqlite", "mysql"。 +# 默认为 "sqlite"，这是最简单的配置，无需外部数据库服务。 +DB_PROVIDER=sqlite + +# --- B1. SQLite 配置 (默认) --- +# [可选] SQLite 数据库文件的存储位置。 +# 如果留空或注释掉，将使用名为 'sqlite-data' 的 Docker 卷进行持久化。 +# 若希望存储在宿主机上，可设置为路径，例如: ./storage # SQLITE_STORAGE_SOURCE=./storage -# 📌 方案一：使用内置 MySQL 数据库（推荐快速体验） -# 启动命令: DB_PROVIDER=mysql docker compose --profile mysql up -d -# 配置如下（保持 MYSQL_HOST=db）： -# MYSQL_HOST=db -# MYSQL_PORT=3306 -# MYSQL_USER=arboris -# MYSQL_PASSWORD=your-database-password-change-me -# MYSQL_DATABASE=arboris -# 内置数据库需要设置 ROOT 密码 -# MYSQL_ROOT_PASSWORD=your-root-password-change-me -# 内置数据库对外暴露的端口（可选，用于外部连接） -# 如果宿主机 3306 端口被占用，修改为其他端口，如 3307 -# MYSQL_EXTERNAL_PORT=3307 +# --- B2. MySQL 配置 (可选) --- +# 如果您希望使用 MySQL，请先将上方的 DB_PROVIDER 设置为 "mysql"，然后根据您的场景选择并配置以下两种方案之一。 -# 📌 方案二：使用外部 MySQL 数据库 +# ▼▼▼ 方案一：使用内置的 MySQL 服务 (推荐用于快速体验) ▼▼▼ +# 启动命令: DB_PROVIDER=mysql docker compose --profile mysql up -d +# +# 注意：以下变量由 docker-compose.yml 中的 `db` 服务使用。 +MYSQL_HOST=db # 使用内置服务时，请勿修改此项 +MYSQL_PORT=3306 +MYSQL_USER=arboris +MYSQL_PASSWORD=your-database-password-change-me +MYSQL_DATABASE=arboris +MYSQL_ROOT_PASSWORD=your-root-password-change-me # 内置数据库需要设置 root 密码 + +# ▼▼▼ 方案二：连接到外部的 MySQL 数据库 ▼▼▼ # 启动命令: DB_PROVIDER=mysql docker compose up -d -# 配置如下（修改 MYSQL_HOST 为外部数据库地址）： +# +# 注意：请确保应用容器可以访问到您的外部数据库地址。 +# `host.docker.internal` 是一个特殊的DNS名，可用于从容器内部访问宿主机。 # MYSQL_HOST=host.docker.internal # MYSQL_PORT=3306 -# MYSQL_USER=root -# MYSQL_PASSWORD=123456 -# MYSQL_DATABASE=arboris -# 注意：使用外部数据库时不需要设置 MYSQL_ROOT_PASSWORD +# MYSQL_USER=your-external-db-user +# MYSQL_PASSWORD=your-external-db-password +# MYSQL_DATABASE=your-external-db-name +# 使用外部数据库时，无需设置 MYSQL_ROOT_PASSWORD。 -# -------------------------------------------- -# 管理员初始化账号 -# -------------------------------------------- + +# ------------------------------------------------------------------- +# C. 初始化管理员账户 +# ------------------------------------------------------------------- +# 应用首次启动时，将使用以下凭据创建默认的管理员账户。 ADMIN_DEFAULT_USERNAME=admin ADMIN_DEFAULT_PASSWORD=ChangeMe123! ADMIN_DEFAULT_EMAIL=admin@example.com -# -------------------------------------------- -# 公共OpenAI / LLM 配置 -# -------------------------------------------- + +# ------------------------------------------------------------------- +# D. 大语言模型 (LLM) 与 RAG 配置 +# ------------------------------------------------------------------- +# --- D1. 主要生成模型配置 --- OPENAI_API_KEY=sk-your-api-key-here OPENAI_API_BASE_URL=https://api.openai.com/v1 OPENAI_MODEL_NAME=gpt-3.5-turbo WRITER_CHAPTER_VERSION_COUNT=2 -# -------------------------------------------- -# SMTP 邮件发送配置 -# -------------------------------------------- +# --- D2. 嵌入模型配置 (用于 RAG 检索) --- +# [必需] 嵌入模型提供方，可选 "openai" 或 "ollama" +EMBEDDING_PROVIDER=openai + +# [可选] OpenAI / 兼容服务的 Base URL，如果留空，将复用上方的 OPENAI_API_BASE_URL +EMBEDDING_BASE_URL=https://api.openai.com/v1 +# [可选] 嵌入模型专用的 API Key，如果留空，将复用上方的 OPENAI_API_KEY +EMBEDDING_API_KEY=sk-your-api-key-here +# [必需] 默认嵌入模型名称 +EMBEDDING_MODEL=text-embedding-3-large +# [必需] 嵌入模型的向量维度，必须与模型匹配；若不确定可保持默认 +EMBEDDING_MODEL_VECTOR_SIZE=3072 + +# [可选] 如果使用 Ollama 本地模型 (EMBEDDING_PROVIDER=ollama)，请配置其服务地址与模型。 +OLLAMA_EMBEDDING_BASE_URL=http://host.docker.internal:11434 +OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest + + +# ------------------------------------------------------------------- +# E. 向量数据库配置 (用于 RAG) +# ------------------------------------------------------------------- +# [可选] RAG 功能依赖向量数据库，默认使用本地文件。 +VECTOR_DB_URL=file:./storage/rag_vectors.db +VECTOR_DB_AUTH_TOKEN= +VECTOR_TOP_K_CHUNKS=5 +VECTOR_TOP_K_SUMMARIES=3 +VECTOR_CHUNK_SIZE=480 +VECTOR_CHUNK_OVERLAP=120 + + +# ------------------------------------------------------------------- +# F. 可选服务与功能开关 +# ------------------------------------------------------------------- +# --- F1. SMTP 邮件发送配置 --- +# [可选] 用于发送注册验证、密码重置等邮件。 SMTP_SERVER=smtp.example.com SMTP_PORT=465 SMTP_USERNAME=no-reply@example.com SMTP_PASSWORD=your-smtp-password EMAIL_FROM=拯救小说家 -# -------------------------------------------- -# 注册与第三方登录开关 -# -------------------------------------------- +# --- F2. 功能开关 --- +# 是否允许新用户注册 ALLOW_USER_REGISTRATION=false +# 是否启用 Linux.do 第三方登录 ENABLE_LINUXDO_LOGIN=false -# -------------------------------------------- -# Linux.do OAuth 配置（如果启用） -# -------------------------------------------- +# --- F3. Linux.do OAuth 配置 (如果启用) --- +# 仅当 ENABLE_LINUXDO_LOGIN=true 时需要配置。 LINUXDO_CLIENT_ID=your_client_id LINUXDO_CLIENT_SECRET=your_client_secret LINUXDO_REDIRECT_URI=https://your-domain.com/api/auth/linuxdo/register