full-stack-ai-agent-template

环境要求

• Python 3.11 及以上（README 徽章标注 python-3.11+）
• 可运行 make 与 uv 的本地开发环境
• Docker（production 等预设需要容器化启动整套服务）
• PostgreSQL（--minimal 预设也包含 PostgreSQL）

安装与启动步骤

1. 1安装 CLI 工具

   README 的 Installation 小节内容缺失，但包已发布到 PyPI（fastapi-fullstack）；此处按该包名给出通用安装命令，如失败请以 PyPI 页面为准。

   pip install fastapi-fullstack

   复制

2. 2创建项目

   用向导生成项目骨架。--preset ai-agent 生成带流式输出的 AI Agent；也可用 production、production-saas，或 --minimal。

   fastapi-fullstack create my_ai_app --preset ai-agent

   复制

3. 3启动后端服务

   进入生成的项目目录后执行 make bootstrap 拉起整个后端；make help 可查看所有可用的快捷命令。

   cd my_ai_app
   make bootstrap

   复制

4. 4启动开发服务器

   带热重载启动后端。命令格式为 uv run <project_slug> <command>，这里的 slug 就是创建时的 my_ai_app。

   uv run my_ai_app server run --reload

   复制

5. 5应用数据库迁移

   把迁移写入数据库；改动模型后先用 db migrate -m "message" 生成迁移，再执行 db upgrade 应用。

   uv run my_ai_app db upgrade

   复制

6. 6创建管理员用户

   生成一个管理员账号，用于登录后台和验证权限。

   uv run my_ai_app user create-admin

   复制

7. 7启动前端

   README 说前端只需一条命令即可运行，但节选中未给出该命令，请用 make help 或查阅官方文档获取。

如何确认成功

make bootstrap 与 server run 均无报错，能打开前端页面并登录；README 未列出默认端口，请以项目配置为准。

常见问题

注意事项

• README 的 Installation 小节在节选中内容缺失，安装命令仅供参考，请以 PyPI 项目页 fastapi-fullstack 的说明为准。
• --minimal 预设不包含 Docker、Redis 和 CI 配置，只带 PostgreSQL。
• CLI 也可用 fastapi-fullstack new 进入交互式配置（如启用 Logfire 并选择要插桩的组件）。
• 项目自带 Makefile，遇到不确定的命令先执行 make help。