feat(server): 统一配置文件管理并增强环境变量配置

- 将服务器配置文件合并到根目录的 .env.example 中，移除 server/.env.example
- 为 PostgreSQL、Redis、MinIO/S3、Server、前端构建和Nginx 配置添加详细注释
- 新增 S3_REGION、S3_PUBLIC_URL 和 SENTRY_DSN 环境变量配置
- 修改配置加载逻辑以正确读取根目录下的 .env 文件
- 更新 docker-compose.yml 以包含新增的环境变量

.env.example

@@ -1,56 +1,109 @@
-# PostgreSQL
+# PostgreSQL 数据库配置
+# PostGIS 镜像地址，可改为私有镜像仓库地址。
 POSTGRES_IMAGE=postgis/postgis:17-3.5
+# PostgreSQL 用户名。
 POSTGRES_USER=shiran
+# PostgreSQL 密码，生产环境必须修改。
 POSTGRES_PASSWORD=change-me-postgres-password
+# PostgreSQL 数据库名。
 POSTGRES_DB=ciyuan_viewfinder
+# 容器内 PostgreSQL 数据目录。
 POSTGRES_PGDATA=/var/lib/postgresql/data/pgdata
 
-# Redis
+# Redis 配置
+# Redis 镜像地址，可改为私有镜像仓库地址。
 REDIS_IMAGE=redis:7-alpine
+# 后端连接 Redis 的地址，Docker Compose 内使用服务名 redis。
 REDIS_URL=redis://redis:6379/0
 
-# MinIO / S3
+# MinIO / S3 对象存储配置
+# MinIO 镜像地址，可改为私有镜像仓库地址。
 MINIO_IMAGE=minio/minio:latest
+# MinIO 管理员用户名。
 MINIO_ROOT_USER=minioadmin
+# MinIO 管理员密码，生产环境必须修改。
 MINIO_ROOT_PASSWORD=change-me-minio-password
+# S3 兼容服务地址，Docker Compose 内使用服务名 minio。
 S3_ENDPOINT=http://minio:9000
+# S3 访问密钥。
 S3_ACCESS_KEY=minioadmin
+# S3 访问密钥密码，通常与 MinIO 管理员密码保持一致。
 S3_SECRET_KEY=change-me-minio-password
+# S3 存储桶名称。
 S3_BUCKET=ciyuan-viewfinder
+# S3 区域，MinIO 可留空。
+S3_REGION=
+# S3 公网访问地址，留空时由后端按默认规则生成。
+S3_PUBLIC_URL=
 
-# Server
+# 后端镜像与运行配置
+# 后端 Dockerfile 基础镜像。
 SERVER_BASE_IMAGE=python:3.12-slim
+# 后端容器内部监听端口。
 SERVER_INTERNAL_PORT=8000
+# pip 包下载源，网络不稳定时可改为内网源。
 PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+# pip 信任主机，通常与 PIP_INDEX_URL 的域名一致。
 PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn
+# pip 下载超时时间，单位秒。
 PIP_DEFAULT_TIMEOUT=120
+# 后端异步数据库连接串，Docker Compose 内使用服务名 postgres。
 DATABASE_URL=postgresql+asyncpg://shiran:change-me-postgres-password@postgres:5432/ciyuan_viewfinder
+# 后端同步数据库连接串，用于迁移等同步场景。
 DATABASE_URL_SYNC=postgresql://shiran:change-me-postgres-password@postgres:5432/ciyuan_viewfinder
+# JWT 签名密钥，生产环境必须改成高强度随机字符串。
 SECRET_KEY=change-me-before-production
+# 访问令牌有效期，单位分钟。
 ACCESS_TOKEN_EXPIRE_MINUTES=43200
+# 刷新令牌有效期，单位天。
 REFRESH_TOKEN_EXPIRE_DAYS=60
+# 存储后端类型，可选 local 或 s3。
 STORAGE_BACKEND=local
+# 本地上传文件在后端容器内的保存路径。
 LOCAL_STORAGE_PATH=/app/uploads
+# 腾讯地图 API Key，没有地图相关能力时可留空。
 TENCENT_MAP_KEY=
+# Sentry DSN，留空表示不启用错误上报。
+SENTRY_DSN=
+# 后端日志级别。
 LOG_LEVEL=INFO
+# 是否输出 JSON 格式日志。
 LOG_JSON=false
 
-# Frontend build
+# 管理端前端构建配置
+# 管理端构建阶段 Node 基础镜像。
 ADMIN_WEB_NODE_IMAGE=node:20-alpine
+# 管理端运行阶段 Nginx 基础镜像。
 ADMIN_WEB_NGINX_IMAGE=nginx:1.27-alpine
+# 管理端容器内部监听端口。
 ADMIN_WEB_INTERNAL_PORT=80
+# 管理端 API 基础路径，浏览器侧使用相对路径走当前域名反代。
 VITE_API_BASE=/api/v1
+
+# 客户端前端构建配置
+# 客户端构建阶段 Node 基础镜像。
 CLIENTS_NODE_IMAGE=node:20-alpine
+# 客户端运行阶段 Nginx 基础镜像。
 CLIENTS_NGINX_IMAGE=nginx:1.27-alpine
+# 客户端容器内部监听端口。
 CLIENTS_INTERNAL_PORT=80
+# H5 客户端 API 基础路径。
 VITE_CLIENT_H5_API_BASE=/api/v1
+# H5 客户端资源服务域名，留空表示使用相对路径。
 VITE_CLIENT_H5_SERVER_ORIGIN=
+# 非 H5 客户端 API 基础路径。
 VITE_CLIENT_NATIVE_API_BASE=/api/v1
+# 非 H5 客户端资源服务域名，留空表示使用相对路径。
 VITE_CLIENT_NATIVE_SERVER_ORIGIN=
 
-# Nginx host ports
+# 外层 Nginx 网关配置
+# 外层 Nginx 镜像地址，可改为私有镜像仓库地址。
 NGINX_IMAGE=nginx:1.27-alpine
+# 外层 Nginx 客户端入口内部监听端口。
 NGINX_CLIENT_INTERNAL_PORT=80
+# 外层 Nginx 管理端入口内部监听端口。
 NGINX_ADMIN_INTERNAL_PORT=81
+# 客户端入口映射到宿主机的端口。
 CLIENT_WEB_PORT=5173
+# 管理端入口映射到宿主机的端口。
 ADMIN_WEB_PORT=5174

docker-compose.yml

@@ -80,7 +80,10 @@ services:
       S3_ACCESS_KEY: "${S3_ACCESS_KEY}"
       S3_SECRET_KEY: "${S3_SECRET_KEY}"
       S3_BUCKET: "${S3_BUCKET}"
+      S3_REGION: "${S3_REGION}"
+      S3_PUBLIC_URL: "${S3_PUBLIC_URL}"
       TENCENT_MAP_KEY: "${TENCENT_MAP_KEY}"
+      SENTRY_DSN: "${SENTRY_DSN}"
       LOG_LEVEL: "${LOG_LEVEL}"
       LOG_JSON: "${LOG_JSON}"
     expose:

server/.env.example

@@ -1,22 +0,0 @@
-DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/ciyuan_viewfinder
-DATABASE_URL_SYNC=postgresql://postgres:postgres@localhost:5432/ciyuan_viewfinder
-REDIS_URL=redis://localhost:6379/0
-SECRET_KEY=change-me-to-a-random-secret-key
-ACCESS_TOKEN_EXPIRE_MINUTES=30
-REFRESH_TOKEN_EXPIRE_DAYS=7
-
-# Storage: "local" or "s3" (s3 compatible with MinIO/OSS/COS)
-STORAGE_BACKEND=local
-LOCAL_STORAGE_PATH=./uploads
-
-S3_ENDPOINT=http://localhost:9000
-S3_ACCESS_KEY=minioadmin
-S3_SECRET_KEY=minioadmin
-S3_BUCKET=ciyuan-viewfinder
-S3_REGION=
-S3_PUBLIC_URL=
-
-# Tencent Maps API Key (apply at https://lbs.qq.com/)
-TENCENT_MAP_KEY=
-
-SENTRY_DSN=

server/app/core/config.py

@@ -1,6 +1,16 @@
+from pathlib import Path
+
 from pydantic_settings import BaseSettings
 
 
+_config_path = Path(__file__).resolve()
+_env_file = (
+    _config_path.parents[3] / ".env"
+    if _config_path.parents[2].name == "server"
+    else _config_path.parents[2] / ".env"
+)
+
+
 class Settings(BaseSettings):
     DATABASE_URL: str
     DATABASE_URL_SYNC: str
@@ -25,7 +35,7 @@ class Settings(BaseSettings):
     LOG_LEVEL: str = "INFO"
 
     class Config:
-        env_file = ".env"
+        env_file = _env_file
 
 
 settings = Settings()