前后端完整可运行项目:
- backend/:FastAPI + SQLite + JWT(含 pytest 用例),启动时自动进行轻量 Schema 升级、写入管理员账号与多组示例导航数据。
- frontend/:Vite + React 多入口(/ 与 /admin),已集成 Axios 鉴权与管理员登录门卫,前台通过
/api/navigation动态获取可公开访问的分类 & 网站卡片。
# 在项目根目录
docker compose up -d --build
# 后端: http://localhost:8000 (Swagger 在 /docs)
# 前端: http://localhost:5173 (admin 在 /admin)docker-compose.yml会构建两个镜像,后端(Python 3.11 + Uvicorn)与前端(Node 构建 + Nginx)。- 如果要更新代码,
docker compose up -d --build即可重新构建并热更新容器。 - 若需要覆盖端口,可修改 compose 文件中的
8000:8000、5173:80。
-
构建前端静态资源
cd frontend npm install npm run build # 将 dist/ 内容复制到 /app/www/tbyenav(或自定义目录) rsync -av dist/ /app/www/tbyenav/
-
运行后端服务(示例:systemd + uvicorn) 创建
/etc/systemd/system/tbyenav.service:[Unit] Description=TbyeNav FastAPI Service After=network.target [Service] # 项目路径(根据你的项目实际目录) WorkingDirectory=/app/TbyeNav/backend # 启动命令:使用虚拟环境中的 uvicorn ExecStart=/app/TbyeNav/backend/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 # 自动重启 Restart=always # 环境变量(防止日志缓存) Environment=PYTHONUNBUFFERED=1 [Install] WantedBy=multi-user.target
sudo systemctl daemon-reload sudo systemctl enable --now tbyenav.service -
配置 Nginx
- 将
deploy/nginx.conf.example拷贝到/etc/nginx/conf.d/tbyenav.conf,根据需要调整server_name与前端目录。 - 关键点:
/api/反向代理到http://127.0.0.1:8000/api/。/与/admin使用try_files回退到构建后的index.html。
sudo nginx -t sudo systemctl reload nginx
- 将
完成以上步骤即可通过 http://your-domain.com 访问前端,/api 由 Nginx 代理至后端 Uvicorn 服务。
cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
# 打开 http://localhost:8000/docs首次启动会自动创建管理员:admin / admin123
cd frontend
cp .env.example .env # 包含 VITE_API_BASE 与 VITE_LOGO_DEV_PUBLIC_KEY
npm install
npm run dev
# 打开 http://localhost:5173/ 与 http://localhost:5173/admin
# 生产构建
npm run build- 当访问
/admin且未登录/非管理员时,会显示登录表单;登录成功后进入后台。 - Axios 拦截器会自动附带 Bearer Token,401 时自动清理本地 Token,后台的分类/卡片/站点信息/备案号都会实时写入数据库。
- 如果设置了
VITE_LOGO_DEV_PUBLIC_KEY(可在 logo.dev 免费申请)且在后台创建站点时未填写图标 URL,将自动按域名拉取站点 Logo;未配置或拉取失败时会回退到内置 SVG 图标。
| 变量 | 作用 | 默认值 |
|---|---|---|
VITE_API_BASE |
前端访问后端接口的根路径 | http://localhost:8000 |
VITE_LOGO_DEV_PUBLIC_KEY |
logo.dev 公共 Token,用于自动生成站点图标 | (空) |
cd backend
pytest -qbackend/
main.py
database.py
settings.py
models/
routers/
schemas/
dependencies/
utils/
tests/
frontend/
index.html # /
admin.html # /admin
src/frontend/ # 前台代码(来自 Material You Navigation Page)
src/admin/ # 后台代码(来自 后台管理系统)
src/shared/ # axios 与 SimpleAdminGate
vite.config.ts # 多入口配置
deploy/
nginx.conf.example # Nginx 手动部署示例
Dockerfile.backend # FastAPI Docker 构建文件
Dockerfile.frontend # Vite/Nginx Docker 构建文件
docker-compose.yml # 一键启动前后端