基于开源项目做二次开发，第一步往往不是急着改业务代码，而是先把关键配置梳理清楚——尤其是涉及安全性的信息（如密钥、数据库账号等），必须替换为自有配置，避免直接沿用默认值带来的安全隐患。
本文记录完整的配置与启动流程，包括后端、前端两部分，以及在过程中遇到的一个典型"坑"及解决方案。
一、后端配置
进入后端目录 backend\env，将 .env.example 文件改名为 .env.dev，然后根据需要进行修改。
1. 修改后端服务端口
修改 SERVER_PORT 字段的值，默认端口为 8001，这里改为 8800：
SERVER_PORT = 8800
2. 修改数据库配置
DATABASE_TYPE = mysql
DATABASE_HOST = localhost
DATABASE_PORT = 3306
DATABASE_USER = root
DATABASE_PASSWORD = 123456
DATABASE_NAME = aitrader
注意：请将
DATABASE_PASSWORD替换为你自己的强密码，尤其是部署到服务器时，切勿继续使用弱口令。
3. 修改 Redis 配置
REDIS_HOST = localhost
REDIS_PORT = 6379
REDIS_USER = ''
REDIS_PASSWORD =
REDIS_DB_NAME = 13
4. 生成 SECRET_KEY
还有一个非常重要的配置——SECRET_KEY。它不在环境变量文件中，而是在设置文件里配置，路径为 backend\app\config\setting.py。可以使用下面的命令生成一个随机密钥：
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 的值：
VITE_PORT = 5880
6. 修改后端接口地址
# 代理目标：本机后端
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 安装依赖
激活虚拟环境并安装依赖：
..venv\Scripts\activate # 激活虚拟环境
pip install -r .\requirements.txt # 安装依赖
7.3 运行后端
python main.py run --env=dev
出现如上图所示的日志，说明系统已经启动。
踩坑记录：环境变量没有生效
按照之前的修改，用 8800 端口访问 Swagger 文档，却发现无法访问：
而当访问 setting.py 里的默认端口时，却能正常访问：
这说明我们设置的环境变量没有起作用。主要原因在于：系统读取环境变量配置的时机太晚了。所以需要对代码做一些调整。
第一步，在 setting.py 中新增一个函数，用于动态获取环境变量配置文件路径：
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 类初始化的时候调用该函数：
def __init__(self, **values: Any):
super().__init__(_env_file=get_env_file_path(), **values)
第三步，在 main.py 中，将引入 settings 的代码放到 run 方法里面，先清除之前的设置缓存，再应用环境变量的配置：
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，配置前端代理，最后启动前后端服务。其中"环境变量不生效"的问题是个很典型的坑，本次记录希望对大家有所帮助。
