ODS Dashboard API开发指南FastAPIVite本地调试工作流完整教程【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODSODS 是一个把 PC、Mac 或 Linux 变成本地 AI 服务器的开源项目内置 LLM 推理、聊天界面、语音、工作流与 RAG 等能力。它的可视化控制台由 React 前端 ODS Dashboard APIPython FastAPI 后端驱动。本文带你掌握 FastAPI Vite 的本地调试工作流免重建镜像、改一行代码即刻热重载是新手快速上手 Dashboard 后端开发的最快路径。先避坑为什么改完代码没反应很多新手第一次改dashboard-api的 Python 文件后刷新页面发现界面纹丝不动——这不是玄学是 Docker 的陷阱镜像在构建时就把源码复制进了容器的/app/目录运行时 uvicorn 加载的是这份烤死的副本宿主机仓库虽然以只读方式挂载进容器用于读取 manifest 和配置但它不在 Python 的导入路径上结论编辑宿主机的.py文件后正在运行的容器不会加载任何变化改动会静默失效。这个坑在官方文档 ods/docs/DASHBOARD-API-DEVELOPMENT.md 中被专门标记为 The Trap官方推荐的做法是把 dashboard 和 dashboard-api 两个容器临时换成宿主机原生进程前端用 Vite 开发服务器后端用带--reload的原生 uvicorn其余服务栈llama-server、host-agent 等照常运行。本地调试架构Vite 代理链一图看懂官方仓库里的 Vite 配置已经预置了代理规则指向 3002 端口的 API 服务位于 ods/extensions/services/dashboard/vite.config.jsserver: { port: 3001, proxy: { /api: { target: http://localhost:3002, changeOrigin: true } } }于是调试时的请求链路非常清晰浏览器 → localhost:3001Vite 开发服务器 → /api/* 自动转发 → localhost:3002宿主机 uvicorn前端 JSX/CSS 由 Vite 热更新后端.py文件由 uvicorn 的 watchfiles 监听热重载两端保存即生效。一键安装本地调试环境准备步骤只需两个一次性初始化步骤分别准备后端虚拟环境和前端依赖# 后端FastAPI 虚拟环境 cd ods/extensions/services/dashboard-api python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 前端安装 Vite 依赖 cd ../dashboard npm install后端核心源码在 ods/extensions/services/dashboard-api/main.py各功能端点按模块拆分在routers/目录下workflows、setup、agents、extensions 等结构说明见 ods/extensions/services/dashboard-api/README.md。每次调试的启动流程3 步走第 1 步停掉两个仪表盘容器释放端口生产模式下Docker 容器占用了宿主机 3001nginx和 3002uvicorn两个端口见 ods/docker-compose.base.yml。必须同时停掉这两个容器——只停 API 容器是错误操作因为前端的 nginx 会把/api/*代理到容器内已消失的 dashboard-api返回 502 Bad Gateway详见 ods/extensions/services/dashboard/nginx.confdocker compose stop dashboard dashboard-api第 2 步终端 1 启动 Vite 开发服务器占用 3001cd ods/extensions/services/dashboard npm run dev第 3 步终端 2 启动原生 uvicorn占用 3002cd ods/extensions/services/dashboard-api source .venv/bin/activate ODS_INSTALL_DIR/path/to/ods \ ODS_DATA_DIR/path/to/ods/data \ ODS_AGENT_HOST127.0.0.1 \ ODS_AGENT_PORT7710 \ DASHBOARD_API_KEY$(grep ^DASHBOARD_API_KEY /path/to/ods/.env | cut -d -f2-) \ ODS_AGENT_KEY$(grep ^ODS_AGENT_KEY /path/to/ods/.env | cut -d -f2-) \ uvicorn main:app --host 127.0.0.1 --port 3002 --reload两个容易踩的参数参数为什么必须设ODS_AGENT_HOST127.0.0.1默认值host.docker.internal只在 Docker 容器内生效原生运行时不设会导致依赖 host-agent 的路由 DNS 解析失败并返回 502两个 KEY 环境变量DASHBOARD_API_KEY与ODS_AGENT_KEY是两个独立的密钥只导出一个会导致 401 鉴权失败完成后浏览器访问http://localhost:3001即可开始开发。调试结束后执行docker compose start dashboard dashboard-api恢复生产容器。跨平台注意事项Windows / macOS / Linux 都支持macOS / Linux原生 uvicorn 开箱即用watchfiles 分别基于 FSEvents 与 inotify热重载快速可靠Windows / WSL2务必把仓库放在WSL2 文件系统内如~/ODS。如果代码放在/mnt/c/...NTFS 挂载盘文件变更事件会丢失或延迟--reload会形同虚设。发布改动docker cp 临时热补丁 vs 重建镜像临时热补丁不想重建镜像时把改好的文件直接拷进容器再重启服务docker cp routers/setup.py ods-dashboard-api:/app/routers/setup.py。注意下次镜像重建后这份副本会被烤死版覆盖正式发布docker compose build dashboard-api docker compose up -d dashboard-api改动才会进入镜像供正式安装使用。关于为什么不直接 bind-mount 源码目录 / 不用--reload覆盖层这两个看似更省事的方案官方文档给出了详细否决理由只读挂载导致 pycache 失败、镜像不再自包含、WORKDIR 陷阱等值得在动手前阅读避免重复踩坑。延伸阅读与相关资源资源说明ods/docs/DASHBOARD-API-DEVELOPMENT.md本指南的官方完整版含所有被否决方案的取舍分析ods/extensions/services/dashboard-api/README.mdAPI 端点全集GPU 监控、服务健康、LLM 指标、工作流、扩展管理等ods/extensions/services/dashboard-api/main.pyFastAPI 应用入口与核心端点ods/extensions/services/dashboard/src/pages/Dashboard.jsx前端仪表盘主页面配合 Vite 热更新调试ods/docs/HOST-AGENT-API.mddashboard-api 调用的 host-agent 端点文档小结掌握 ODS Dashboard API 的本地调试工作流只需记住三句话停双容器、跑 Vite、起 uvicorn。Vite 代理与端口配置官方已预置好你只需要保证环境变量正确、代码树位于平台文件系统内就能获得保存即生效的丝滑开发体验——这也是 FastAPI Vite 组合在本地 AI 基础设施项目中的最佳实践。【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考