FastapiAdmin 实战：二次开发前的准备（环境配置与项目启动）

基于开源项目做二次开发，第一步往往不是急着改业务代码，而是先把关键配置梳理清楚------尤其是涉及安全性的信息（如密钥、数据库账号等），必须替换为自有配置，避免直接沿用默认值带来的安全隐患。

本文记录完整的配置与启动流程，包括后端、前端两部分，以及在过程中遇到的一个典型"坑"及解决方案。

一、后端配置

进入后端目录 backend\env，将 .env.example 文件改名为 .env.dev，然后根据需要进行修改。

1. 修改后端服务端口

修改 SERVER_PORT 字段的值，默认端口为 8001，这里改为 8800：

ini 复制代码

SERVER_PORT = 8800

2. 修改数据库配置

ini 复制代码

DATABASE_TYPE = mysql
DATABASE_HOST = localhost
DATABASE_PORT = 3306
DATABASE_USER = root
DATABASE_PASSWORD = 123456
DATABASE_NAME = aitrader

注意：请将 DATABASE_PASSWORD 替换为你自己的强密码，尤其是部署到服务器时，切勿继续使用弱口令。

3. 修改 Redis 配置

ini 复制代码

REDIS_HOST = localhost
REDIS_PORT = 6379
REDIS_USER = ''
REDIS_PASSWORD =
REDIS_DB_NAME = 13

4. 生成 SECRET_KEY

还有一个非常重要的配置------SECRET_KEY。它不在环境变量文件中，而是在设置文件里配置，路径为 backend\app\config\setting.py。可以使用下面的命令生成一个随机密钥：

scss 复制代码

python -c "import secrets; print(secrets.token_hex(32))"

二、前端配置

进入前端目录 frontend\web，将 .env.development.example 文件改名为 .env.development，将 .env.production.example 文件改名为 .env.production，然后根据需要进行修改。

5. 修改前端端口

在 .env 文件中修改 VITE_PORT 的值：

ini 复制代码

VITE_PORT = 5880

6. 修改后端接口地址

ini 复制代码

# 代理目标：本机后端
VITE_API_BASE_URL = http://127.0.0.1:8800
# 是否删除控制台输出
VITE_DROP_CONSOLE = false
# WebSocket 端点（AI 对话功能需要配置）
VITE_APP_WS_ENDPOINT = ws://localhost:8800

三、启动项目

7. 启动后端

7.1 创建虚拟环境

在 backend 目录下执行以下命令，创建一个名为 .venv 的虚拟环境：

复制代码

python -m venv .venv

7.2 安装依赖

激活虚拟环境并安装依赖：

bash 复制代码

..venv\Scripts\activate           # 激活虚拟环境
pip install -r .\requirements.txt  # 安装依赖

7.3 运行后端

css 复制代码

python main.py run --env=dev

出现如上图所示的日志，说明系统已经启动。

踩坑记录：环境变量没有生效

按照之前的修改，用 8800 端口访问 Swagger 文档，却发现无法访问：

而当访问 setting.py 里的默认端口时，却能正常访问：

这说明我们设置的环境变量没有起作用。主要原因在于：系统读取环境变量配置的时机太晚了。所以需要对代码做一些调整。

第一步，在 setting.py 中新增一个函数，用于动态获取环境变量配置文件路径：

python 复制代码

def get_env_file_path() -> tuple[Path, ...]:
    """动态获取环境变量配置文件路径"""
    env_name = os.getenv("ENVIRONMENT") or "dev"
    env_file = ENV_DIR / f".env.{env_name}"
    fallback_file = ENV_DIR / ".env"

    files: list[Path] = []
    if fallback_file.exists() and fallback_file.is_file():
        files.append(fallback_file)
    if env_file.exists() and env_file.is_file():
        files.append(env_file)
    elif not files:
        files.append(env_file)
    return tuple(files)

第二步，在 Settings 类初始化的时候调用该函数：

scss 复制代码

def __init__(self, **values: Any):
    super().__init__(_env_file=get_env_file_path(), **values)

第三步，在 main.py 中，将引入 settings 的代码放到 run 方法里面，先清除之前的设置缓存，再应用环境变量的配置：

scss 复制代码

from app.config.setting import get_settings

get_settings.cache_clear()
current_settings = get_settings()

重新启动后端，即可正常访问 Swagger 文档：

8. 启动前端

8.1 安装依赖

执行以下命令，安装前端依赖：

复制代码

pnpm install

如图所示，即代表依赖安装成功。

8.2 启动前端服务

执行以下命令，启动前端服务：

复制代码

pnpm dev

看到如图所示的内容，说明启动成功。

8.3 访问系统

访问 http://localhost:5880/web 进行登录，进入首页后，即代表整个项目启动成功。

小结

以上就是 FastapiAdmin 二次开发前的完整准备流程：修改后端端口、数据库与 Redis 配置，生成 SECRET_KEY，配置前端代理，最后启动前后端服务。其中"环境变量不生效"的问题是个很典型的坑，本次记录希望对大家有所帮助。