Windows/Linux 自动适配 + Pydantic Settings 配置

，config.py 是整个后端服务的"总配置中枢"，所有路径、接口地址、并发控制、开关模式都在这里统一管理。

很多同学刚接触时会困惑：

这些 Field 是干嘛的？
为什么 Windows 和 Linux 路径不一样？
这个配置到底给谁用、谁在调用？

一、文件整体作用

config.py = 项目全局配置管家

统一管理：

服务启动地址、端口
文件存储路径（自动适配 Windows/Linux）
外部接口地址
模板缓存目录
接口超时、并发限制
本地模拟数据开关（Mock 模式）
AI 绘图接口调用方式

一套代码，Windows 开发、Linux 部署自动切换，无需手动改路径。

二、完整代码 + 逐行说明

1. 导入依赖 + 系统判断工具

python 复制代码

import platform
from pathlib import Path
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field

platform：判断当前是 Windows 还是 Linux
Path：处理文件路径，兼容不同系统
BaseSettings：Pydantic 配置类，自动读 .env
Field：给配置项设置动态默认值、别名、说明

2. 判断是否为 Windows 系统

python 复制代码

def _is_windows() -> bool:
    return platform.system() == "Windows"

作用：返回 True = Windows，False = Linux/Mac

3. 动态默认值函数（核心：自动切换路径）

3.1 默认数据存储目录

python 复制代码

def _default_data_dir() -> str:
    if _is_windows():
        return "D:/AICreama/booth/data"  # 本地开发用
    return "/data"                      # Linux 服务器用

Windows：数据存在 D 盘
Linux：直接存在根目录 /data

3.2 外部访问地址

python 复制代码

def _default_public_base_url() -> str:
    if _is_windows():
        return "http://127.0.0.1:9002"
    return "http://127.0.0.1:9002"

本地开发/测试都用本地回环地址。

真实部署 Linux 时可改为容器内部服务名 http://pipeline:9002。

3.3 平台接口地址

python 复制代码

def _default_platform_base_url() -> str:
    if _is_windows():
        return "http://127.0.0.1:8089"
    return "http://127.0.0.1:8089"

8089 是平台后端接口，9002 是当前图片服务。

3.4 模板缓存目录

python 复制代码

def _default_template_cache_dir() -> str:
    return str(Path(_default_data_dir()) / "_templates")

自动拼路径：

Windows：D:/AICreama/booth/data/_templates
Linux：/data/_templates

3.5 本地 Mock 数据目录

python 复制代码

def _default_platform_mock_dir() -> str:
    return str(Path(__file__).resolve().parent / "mocks")

存放模拟接口返回的 JSON 文件，用于离线开发、不连后端也能调试。

三、Settings 配置类详解（核心重点）

python 复制代码

class Settings(BaseSettings):
    # 自动读取 .env 文件，忽略多余字段
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

3.1 服务启动配置

python 复制代码

PIPELINE_HOST: str = "0.0.0.0"       # 允许任何IP访问
PIPELINE_PORT: int = 9002            # 图片服务端口

3.2 数据目录（动态默认值）

python 复制代码

PIPELINE_DATA_DIR: str = Field(
    default_factory=_default_data_dir,  # 自动判断系统路径
    validation_alias="PIPELINE_DATA_DIR"
)

BOOTH_DATA_DIR: str = Field(
    default_factory=_default_data_dir,
    validation_alias="BOOTH_DATA_DIR"
)

default_factory：动态生成默认值（不是写死）
validation_alias：允许从环境变量/ .env 覆盖配置

3.3 外部访问地址

python 复制代码

PUBLIC_BASE_URL: str = Field(
    default_factory=_default_public_base_url
)

给前端返回的图片访问域名。

3.4 并发控制

python 复制代码

MAX_SEGMENT_CONCURRENCY: int = 1   # 人像抠图最大并发
MAX_BG_CONCURRENCY: int = 1        # 背景处理最大并发

防止显卡/CPU 爆掉。

3.5 模板缓存目录

python 复制代码

TEMPLATE_CACHE_DIR: str = Field(
    default_factory=_default_template_cache_dir
)

3.6 平台接口配置

python 复制代码

PLATFORM_BASE_URL: str = Field(
    default_factory=_default_platform_base_url
)

PLATFORM_TIMEOUT_MS: int = Field(default=5000)  # 接口超时5秒

3.7 本地 Mock 开关（超级常用）

python 复制代码

PLATFORM_MOCK_ENABLED: bool = Field(
    default=False,
    description="True=使用本地假数据，False=调用真实平台接口"
)
PLATFORM_MOCK_DIR: str = Field(default_factory=_default_platform_mock_dir)
PLATFORM_MOCK_FILE: str = Field(default="platform_resolve_mock.json")

开发神器：

后端没联通 → 开 Mock → 直接读本地 JSON
后端通了 → 关 Mock → 正常调用接口

3.8 AI 绘图 HTTP 客户端

python 复制代码

WAN26_HTTP_CLIENT: str = Field(
    default="httpx",
    description="选择 httpx 或 requests 发请求"
)

四、最终创建全局配置实例

python 复制代码

settings = Settings()

这一行是全项目入口

其他所有文件都这么用：

python 复制代码

from config import settings

# 读取路径
settings.PIPELINE_DATA_DIR

# 读取接口地址
settings.PLATFORM_BASE_URL

# 判断是否开启Mock
if settings.PLATFORM_MOCK_ENABLED:
    ...

五、Windows 与 Linux 区别对照表

配置项	Windows 默认值	Linux 默认值
数据目录	D:/AICreama/booth/data	/data
模板缓存	D:/AICreama/booth/data/_templates	/data/_templates
图片服务地址	http://127.0.0.1:9002	http://127.0.0.1:9002
平台接口地址	http://127.0.0.1:8089	http://127.0.0.1:8089
Mock 目录	项目下 mocks 文件夹	项目下 mocks 文件夹

六、谁在调用 config.py？

下面这些模块全都依赖 config：

FastAPI 启动服务 → 读 HOST、PORT
图片上传/保存 → 读 DATA_DIR
证件照模板加载 → 读 TEMPLATE_CACHE_DIR
调用平台接口 → 读 PLATFORM_BASE_URL
本地离线调试 → 读 PLATFORM_MOCK_ENABLED
AI 绘图增强 → 读 WAN26_HTTP_CLIENT

config 是整个后端的"神经系统"。

七、为什么这么设计？

统一配置，一改全改
自动适配 Windows/Linux，不用手动改路径
支持 .env 环境变量，安全不泄露
Mock 模式支持离线开发
类型安全，避免写错路径、端口

八、总结

config.py = 项目全局配置中心
Field(default_factory=...) = 动态默认值，自动切系统
settings = Settings() = 全项目唯一配置实例
所有路径、地址、开关、并发都在这里管
Windows 开发、Linux 部署一套代码通用