Tabby UI 本地开发环境搭建指南：Caddy 编排前后端联调与生产静态资源分发

Tabby UI 本地开发环境搭建指南Caddy 编排前后端联调与生产静态资源分发【免费下载链接】tabbySelf-hosted AI coding assistant项目地址: https://gitcode.com/GitHub_Trending/tab/tabby导读Tabby 是一个自托管的 AI 编程助手self-hosted AI coding assistant而 Tabby UI 是其 Web 管理界面Next.js 应用承载登录注册、聊天、代码搜索、系统设置、报表等全部前端交互。本指南基于ee/tabby-ui/README.md完整还原 Tabby UI 的本地开发环境搭建流程讲解开发模式下如何用 Caddy 把 Next.js 前端默认 3000 端口与 Tabby 后端服务默认 8081 端口编排在同一个 8080 入口下并深入生产构建路径Tabby UI 仅产出静态资源由 Tabby 二进制内嵌分发。读完本文你将掌握从零启动一套前后端联动开发环境的方法并理解其背后的路由编排与静态资源嵌入原理。Tabby UI 在仓库中的定位Tabby UI 位于 ee/tabby-ui是一个基于 Next.js 13 的 TypeScript 应用。从目录结构可以清晰看到它承载的功能模块app/(dashboard)仪表盘、活动、报表、设置集成、SSO、订阅、团队、系统状态等管理页面app/chat、app/search、app/files、app/pages聊天、代码搜索、文件浏览与页面管理四大核心业务页面components/基于 Radix UI 与 Tailwind CSS 的通用 UI 组件库、CodeMirror 代码编辑封装、Markdown 渲染与提示词编辑器lib/GraphQL 客户端urql、状态管理zustand、各类业务 hooks。前端通过 GraphQL 与后端通信package.json中声明了graphql、urql、graphql-ws等依赖并通过codegen脚本graphql-codegen根据后端 GraphQL Schema 自动生成类型安全的查询代码见 ee/tabby-ui/codegen.ts。开发模式的双服务架构README 明确指出本地开发的编排思路同时运行 Tabby UI 前端服务与本地 Tabby 后端服务用 Caddy 将前端与后端请求分别转发到各自的服务器。这样做的好处是无需在代码里配置复杂的 host/port前端直接访问统一入口http://localhost:8080路径即服务浏览器不会遇到跨域问题充分利用 Next.js 的 hot-reload 特性改代码即时生效。开发模式下的进程拓扑如下Tabby UI 前端Next.js dev server监听localhost:3000负责页面渲染与热更新Tabby 后端Rust webserver监听localhost:8081提供 GraphQL API、REST API 与 WebSocketCaddy 反向代理监听localhost:8080按路径把请求分流到 3000 或 8081。本地开发前置条件开始前请确认本机具备以下工具链与仓库 CI/构建脚本保持一致Node.js 与 pnpm仓库使用 pnpm workspace 管理多包依赖见 pnpm-workspace.yamlTabby UI 的package.json依赖tabby-chat-panel等 workspace 包因此必须在仓库根目录执行pnpm install安装全部依赖Rust 工具链用于编译运行cargo run serve启动的 Tabby 后端依赖tabby-webserver、tabby-schema、tabby-db等 crateCaddy本地反向代理配置文件为 ee/tabby-webserver/development/Caddyfile可选tmux 与 tmuxinator用于make dev一键启动。三步启动开发环境按 README 的指引启动顺序为前端 → 后端 → Caddy。以下逐步展开。1. 启动开发前端服务器cd tabby/ee/tabby-ui pnpm devpnpm dev实际由npm-run-all并发执行两个子任务见 ee/tabby-ui/package.jsondev:nextnext dev启动 Next.js 开发服务器默认 3000 端口dev:codegenpnpm codegen启动 GraphQL Codegen 从后端 Schema 生成前端类型与查询文档保证前端调用与后端 GraphQL 定义一致。生产构建时也有对应钩子prebuild会先执行pnpm codegen再执行next build确保类型生成不缺失。2. 启动开发后端服务器cargo run serve --port 8081该命令在仓库根目录执行编译并启动 Tabby 主程序入口为 crates/tabby/src/main.rs 与 crates/tabby/src/serve.rs通过--port 8081显式指定监听端口与 Caddyfile 中的后端转发目标对应。后端同时提供 GraphQL/graphql、订阅/subscriptions、REST API/v1/*、/v1beta/*等接口。3. 启动 Caddy 服务器make caddyMakefile 中并无caddy目标此处实际对应的命令是见 .tmuxinator/tabby.ymlcaddy run --watch --config ee/tabby-webserver/development/Caddyfile--watch让 Caddy 在 Caddyfile 变更时自动重载便于调试路由规则。4. 开始开发调试打开http://localhost:8080即可看到 Tabby webserver 的完整界面。前端请求页面路由被转发到 Next.js3000后端请求API被转发到 Rust 服务8081热更新生效后前端代码改动会即时反映到浏览器。Caddyfile 路由编排详解Caddyfile 是整个本地联调的核心值得逐段拆解:8080 { rewrite /files/* /files rewrite /search/* /search rewrite /pages/* /pages backend { path /graphql path /graphiql path /subscriptions path /v1/* path /v1beta/* path /hub path /repositories/* path /oauth/* path /avatar/* path /integrations/github/* path /background-jobs/* path /swagger-ui path /swagger-ui/* path /api-docs/* } handle backend { reverse_proxy localhost:8081 } handle /* { reverse_proxy localhost:3000 } }要点说明rewrite /files/* /files等三条规则将/files/xxx、/search/xxx、/pages/xxx深层路径统一重写到顶层路由交由 Next.js 处理因为这几个页面在 Next.js 中本身就是顶级路由深层路径由前端内部状态驱动backend匹配器用 named matcher 汇集所有需要转发给后端的路径——GraphQL 端点/graphql、/graphiql、/subscriptions、REST API/v1/*、/v1beta/*、Hub 实时通道/hub、仓库/repositories/*、OAuth/oauth/*、头像/avatar/*、GitHub 集成/integrations/github/*、后台任务日志/background-jobs/*以及 Swagger/API 文档handle backend命中上述路径的请求反向代理到localhost:8081Tabby 后端handle /*其余请求页面、_next静态资源等全部转发到localhost:3000Next.js 前端。这套配置把前端渲染与后端 API在同一个入口下彻底解耦前端代码中无需关心后端地址浏览器也规避了 CORS 配置成本。make dev 一键启动README 提到可以运行make dev同时启动上述所有命令。其实现位于 Makefiledev: tmuxinator start -p .tmuxinator/tabby.yml对应的 tmuxinator 配置 .tmuxinator/tabby.yml 定义了三个 panewindows: - caddy: panes: - caddy run --watch --config ee/tabby-webserver/development/Caddyfile - server: layout: even-horizontal panes: - cargo run serve --port 8081 - cd ee/tabby-ui pnpm dev即一个窗口运行 Caddy另一个窗口左右分屏同时运行后端与前端。前提是系统已安装tmux与tmuxinator。生产模式静态导出与内嵌分发README 特别强调在生产发行版中不会启动 tabby-ui 服务与 Caddy 服务tabby-ui 只负责构建产出静态资源路由由 Tabby 内部配置分发。这一设计从源码侧可以完整印证1. 静态导出ee/tabby-ui/next.config.js 配置了module.exports { reactStrictMode: true, output: export, images: { unoptimized: true }, };output: export使next build输出纯静态 HTML/JS/CSS默认到out/目录不依赖 Node 运行时图片也不做服务端优化unoptimized。2. 构建产物汇入 webserverMakefile 的update-ui目标负责把前端构建产物与邮件模板一并拷入 webserverupdate-ui: pnpm build rm -rf ee/tabby-webserver/ui cp -R ee/tabby-ui/out ee/tabby-webserver/ui rm -rf ee/tabby-webserver/email_templates cp -R ee/tabby-email/out ee/tabby-webserver/email_templates最终静态文件落在ee/tabby-webserver/ui/即仓库中的ui/目录含各页面的.html/.txt及_next/资源。3. 编译期内嵌与路由分发ee/tabby-webserver/src/routes/ui.rs 使用rust-embed在编译期把./ui目录整体嵌入二进制#[derive(rust_embed::RustEmbed)] #[folder ./ui] struct WebAssets;其 fallback handler 承担了与开发模式 Caddyfile 等价的职责空路径映射到index.htmlfiles/、search/、pages/前缀根据请求中是否携带_rsc参数分别映射到对应的.txtRSC payload或.html页面其余无扩展名路径尝试追加.html_next/静态资源设置Cache-Control: public, max-age6048007 天其余按 MIME 类型返回未命中的资源回退到404.html。同时 ee/tabby-webserver/src/routes/mod.rs 把 UI 路由注册为整体 fallbackui.fallback(ui::handler)并在/graphiql挂载 GraphiQL 调试器后端 API 路由与前端静态页面路由在同一 axum 服务中并存。整个 webserver 的装配入口在 ee/tabby-webserver/src/webserver.rs。由此可见开发模式与生产模式共用同一套路径即页面、API 走专用路径的路由心智模型开发时 Caddy 替代了后端 fallback 做分流生产时 axum 路由直接内嵌分发二者语义一致这正是这套架构的精妙之处。常见问题与排障建议前端启动报 workspace 依赖缺失Tabby UI 依赖tabby-chat-panel、tabby-openapi等 workspace 包务必在仓库根目录pnpm install后进入子目录启动Codegen 失败pnpm dev中的dev:codegen需要后端 GraphQL Schema 可访问可先启动后端cargo run serve再启动前端或改用pnpm dev:next单独跑前端package.json 中的脚本是并发的必要时可拆分执行8080 打不开确认三个进程均存活且 Caddy 以--config ee/tabby-webserver/development/Caddyfile指向仓库内配置文件路径 404检查请求路径是否命中 Caddyfile 的backend集合——凡后端 API 均需落在该集合内否则会被当作前端路由转发到 3000生产构建差异next build的产物是纯静态导出任何依赖 Node 运行时或服务端渲染的能力都不会生效所有页面需由ui::handler的路径映射规则覆盖。总结Tabby UI 的开发体验建立在Caddy 统一入口 前后端双进程的编排之上pnpm dev提供带热更新的 Next.js 前端cargo run serve --port 8081提供 GraphQL/API 后端Caddy 按路径精确分流而进入生产后前端静态导出经rust-embed内嵌进 Tabby 二进制由 axum 的 fallback 路由直接分发。理解这两套模式的等价映射关系即可快速上手 Tabby UI 的本地开发也能在排查生产环境静态资源问题时直击要害。【免费下载链接】tabbySelf-hosted AI coding assistant项目地址: https://gitcode.com/GitHub_Trending/tab/tabby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考