关于 Flisk
Flisk 是用于本地运行应用服务的命令行工具,服务配置来自 service.json。它生成并跟踪开发环境文件,支持热重载,也可为 Agent 提供管理 Flisk 项目的 MCP 服务。
主要功能
- 01根据 service.json 生成开发文件
- 02通过本地网关启动服务
- 03文件变更时重新加载服务
- 04配置服务 URL 和环境变量
- 05检查生成文件的偏差
- 06通过检查点和路由运行 Agent 服务
适用场景
- 01在本地启动多服务应用
- 02导入现有 Compose 项目
- 03为 Agent 提供管理服务栈的工具
- 04让 Agent 与其工具及数据库共同运行
MCP 相关
`flisk mcp` 通过 stdio 运行 MCP 服务,并向 Agent 提供 21 个工具。`flisk connect` 可为受支持的 Agent 添加服务配置。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
21收录的工具列表 · 更新于 今天
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| noPing | boolean | 否 | 跳过对运行中服务的健康检查端点执行 ping |
| projectPath | string | 否 | Flisk 项目根目录的绝对路径;从该目录运行此操作。 |
详细介绍
Flisk:只需一条命令,即可在你的电脑上运行整个应用
什么是 Flisk? · 主要功能 · 快速开始 · 命令 · 配置 · 与 AI Agent 搭配使用 · 常见问题 · 文档
👋 欢迎 · 欢迎 · 歡迎 · ようこそ · 환영합니다 · Bienvenue · Bienvenido · Bem-vindos · Willkommen · Benvenuti · Bun venit · أهلًا · Hoş geldiniz · Ласкаво просимо · Witamy · خوش آمدید · Selamat datang · Chào mừng · ยินดีต้อนรับ · Καλώς ήρθατε · സ്വാഗതം
什么是 Flisk?
Flisk 是一款用于本地开发的命令行工具。它会在你的电脑上通过一个本地地址运行应用的各个部分(API、网站、工作进程、AI Agent、数据库),并在你保存时重新加载相应部分。你只需在简短的 service.json 中描述各个部分;Flisk 会据此生成 Dockerfile、Compose 文件和 Tiltfile,并让它们保持同步。它不会进行部署:生产环境仍由你自己的工具管理。
npm install -g @flisk-sh/flisk
mkdir my-shop && cd my-shop
flisk project --yes
flisk resource orders-api --type backend --stack shop --yes
flisk resource shop-web --type frontend --stack shop --yes
flisk up shop
这会在一个网关后启动订单 API 和店面,并配备 Postgres 和实时重新加载,同时打印它们的 URL。你需要安装 Docker、Tilt、Node.js 22.12+ 和 Bun 1.2+;运行 flisk doctor 即可查看缺少哪些依赖。小型应用可以跳过 Docker,作为本地进程运行。
每个服务只需一个小文件
flisk resource 为每个部分生成了一个 service.json。这是订单 API 的完整文件,也是你为它编辑的唯一配置:
{
"$schema": "https://flisk.sh/schema.service.json",
"schemaVersion": 1,
"appName": "orders-api",
"appType": "backend",
"stack": "shop",
"port": 4000,
"healthCheckPath": "/health"
}
Flisk 会据此生成 Dockerfile、Compose 条目、网关路由、健康检查和 DATABASE_URL;如果其中任意文件被手动编辑,它就会拒绝启动。所有字段 · Flisk 为你生成的所有内容
已有 docker-compose.yml?
flisk import . 会为每个 Compose 服务写入一个 service.json,并保留其端口、名称和环境变量值:
flisk import .
flisk up
一个普通的 Compose 应用(包含 Node API 和 Postgres)在全新的 Ubuntu CI 运行器上,通过 Flisk 路由器响应请求,耗时从执行 flisk import 起 49 s;镜像从头拉取并构建,不计安装时间(运行记录,相关声明)。CI 会在每个拉取请求上重复运行此测试。
更想请 AI 助手帮忙? 它会替你运行这些命令:复制提示词。从未写过代码? 从这里开始,一步一步来 · 你会遇到的术语
主要功能
- 每个服务对应一个
service.json。 Flisk 会据此生成 Dockerfile、Compose 条目、Traefik 路由、健康检查和 Tiltfile。你无需手写docker-compose.yml或nginx.conf。 - 一条命令,一个地址。
flisk up会启动 Postgres、你的服务和本地网关,按通过健康检查的dependsOn顺序启动服务,并为每个服务打印一个*.localhostURL。 - 编码时热重载。 保存文件时,Tilt 会实时更新容器;无需重新构建。
- 自动接线。 系统会生成并注入
DATABASE_URL、前端调用的 API URL,以及JWT_SECRET等缺失的密钥,无需手动复制。 - 生成的文件可供检查。 Flisk 会记录写入的内容;如果有人手动编辑了生成的文件,Flisk 会拒绝启动;
flisk config verify会报告偏差(生成的文件和偏差检查)。 - 为 AI 助手打造。
flisk mcp为 Claude Code、Codex、Cursor 和其他 Agent 提供 21 个工具;flisk project则会添加 Flisk 技能和AGENTS.md。 - 也能运行 AI Agent。 Agent 服务支持持久化检查点、粘性
x-session-id路由,以及/health和/ready检查(下文)。 - 无需 Kubernetes;小型应用无需 Docker。 Docker 和 Tilt 无需本地集群(如 kind 或 minikube)即可运行整个栈;各自声明了
command的服务会作为普通本地进程运行。 - 快速启动。 使用已缓存的镜像层时,单后端栈在 12.8 到 13.8 秒内即可通过健康检查(计时说明)。包含 8 个服务的栈,在缓存镜像时需要 32 到 42 秒,首次冷构建则需要约 4.5 分钟(基准测试)。
- 核心功能免费。 CLI 采用 MIT 许可证,运行
flisk up无需密钥;Premium 扩展功能为可选项(许可证对照表)。
Flisk 适合你的团队吗?
三个简单问题;点击最符合你团队情况的答案。不熟悉技术?遇到不确定的地方就选“不确定”。你会得到一个分数,以及通俗易懂的原因说明。
| 1. 这个应用是用什么编写的? |
| 2. 开发者现在如何在笔记本电脑上启动应用? |
| 3. 这个应用由多少个部分组成?(网站、API、后台任务……) |
非常适合。 Flisk 正是为你这样的团队打造的。为什么是这个分数 → · 在 flisk.sh 上使用完整计算器
信赖 Flisk 的团队
![]() | ![]() | ![]() | ![]() |
这些团队在自己的代码上运行 flisk up,并已同意列出。查看所有采用者,或添加你的团队。
将 Flisk 与你的 AI Agent 搭配使用
AI 助手擅长编写应用,却不擅长处理周边的配置:每次它手动重写 Dockerfile、Tiltfile 或 nginx.conf,总会出问题,你还得花时间和 token 修复。Flisk 每次都会用同样的方式生成这些配置,让你和助手专注于应用本身。
这是一段在 Warp 终端中使用 Claude Code 的示例会话。Flisk 命令、命令输出以及 Flisk 打印的 URL 均来自真实运行。
安装 Flisk,然后将提示词粘贴到 Claude Code、Codex、Cursor,或任何能够运行命令的AI 助手中:
npm install -g @flisk-sh/flisk
Build me a small online shop with a storefront and an orders API, and run it on my laptop with Flisk.
助手会创建项目、添加各个部分并启动项目,然后提供可打开的链接。如果缺少什么,flisk doctor 会用通俗易懂的话说明。
更多可复制的提示词
为现有项目添加服务
Use Flisk to add a backend service called payments-api to my shop stack, then start the stack and give me the URLs.
构建带有工具和数据库的 AI Agent
Use Flisk to scaffold an AI agent, an MCP tools server, and a database in one stack called shop, then start it and tell me how to talk to the agent.
遇到问题时
Run flisk doctor, explain every problem in plain words, and fix what you can. Then start my stack with flisk up.
查看正在运行的内容
Use flisk status to tell me which services are running, which are unhealthy, and what URL each one has.
停止所有内容
Stop my Flisk stack with flisk down and confirm nothing is left running.
每种助手的安装方式略有不同;选择你的助手,查看具体步骤。已有项目?运行 flisk connect claude(或 cursor、codex),即可添加 flisk mcp 服务(21 个工具)和 Flisk 技能,安装到该 Agent 读取技能的位置;添加 --dry-run 可先查看文件。Agent 随后能做什么:面向 AI Agent 的 Flisk。
然后在项目文件夹中输入 |
任何能够运行终端命令的其他 Agent 也可以使用:让它读取 AGENTS.md,或将它连接到 flisk mcp,后者会通过 stdio 运行 MCP 服务。flisk project 会将 Flisk 技能(构建技术栈、网店、SaaS、AI Agent 和博客的配方,以及 doctor、up、resource、status、troubleshoot;源文件位于 .agents/skills)和 AGENTS.md 添加到项目中,以便 Agent 检查你的设置并解释失败原因,而不是猜测 Docker 或 Tilt 配置。按类别整理的更多提示词,请参阅提示词库。
手边没有终端?在 GitHub Codespaces 或 Gitpod 中打开 Flisk starter,或选择其他一键启动选项。
在服务旁运行 AI Agent
Flisk 是 Agent 系统的本地运行时:Agent、它的 MCP 工具、数据库和队列,都置于同一个网关之后,只需一条命令即可运行。
# Scaffold an agent, an MCP tools server, and a database in one stack
flisk resource bot --type agent --stack shop --yes
flisk resource tools-mcp --type mcp --stack shop --yes
flisk up shop
Agent 会获得持久化检查点卷,即使运行 flisk down 也能保留;通过 x-session-id 实现粘性会话路由;热重载时优雅地处理 SIGTERM 并排空请求;在 /health 上执行 Docker 健康检查;并在 /ready 上执行应用级就绪检查。请参阅 AI Agent 指南和与 Agent 框架的客观比较。
前置条件(安装一次即可)
| 工具 | 版本 | 安装方式 | 用途 |
|---|---|---|---|
| 应用所用的运行时 | 取决于应用使用的运行时 | Node.js、Python、Go、Bun 等 | 所有运行方式:用于运行代码 |
| Node.js | 22.12+ | nodejs.org | npm 安装(npm install -g @flisk-sh/flisk) |
| Docker | Engine 25+,Compose 2.20.2+ | docker.com | 仅用于 Docker + Tilt 方式 |
| Tilt | 0.25+ | curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash | 仅用于 Docker + Tilt 方式 |
| Bun | 1.2+ | curl -fsSL https://bun.sh/install | bash | Bun 安装(bun add -g @flisk-sh/flisk),或生成 JavaScript 服务 |
两种运行方式。 如果项目中的每项服务都声明了
command,Flisk 会将它们作为本地进程运行:只需要 Flisk 和应用所用的运行时(最简单的方式)。如果需要数据库、供所有服务共用的网关 URL,或与部署时相同的容器,则需要 Docker 和 Tilt。flisk doctor只会检查项目实际使用的内容。
设置你的电脑。选择系统:
|
只需一次即可完成 Mac 的准备工作。将每个灰色框中的内容粘贴到终端(按下 Cmd+Space,输入 1. 安装 Node.js 22.12+,从 nodejs.org 获取;如果应用使用的不是 JavaScript,还需安装应用所用的语言。小型应用只需这些:最简单的方式。 2. 仅适用于较大型的应用(需要数据库、让所有部分共用一个地址,或使用与部署时相同的容器):启动 Docker Desktop、OrbStack 或 Colima,并安装 Tilt:
3. 安装 Flisk 并检查 Mac:
|
可通过 npm、Bun 或预构建二进制文件安装 CLI,无需 Node.js 或 Bun:
这会通过 npm 下载 Flisk,npm 随附 Node.js 22.12+。使用 **面向开发者:**推荐默认使用公共 npm;如需改用 GitHub Packages 安装,请按GitHub Packages 安装说明配置注册表身份验证。 |
之后可使用 flisk upgrade(或其别名 flisk update)更新,也可运行 npm install -g @flisk-sh/flisk@latest。如需固定版本或查看变更内容,请参阅升级和固定版本。
重要
请从 flisk-sh/flisk 仓库、
@flisk-sh/flisknpm 包或 官方网站获取 Flisk。请通过这些官方来源中的安装链接进行安装。 仓库名称相似或 README 被复制,都不能证明下载内容是官方的。
快速开始
准备好先决条件(安装一次即可)后,Flisk 是什么?下的命令就是完整的快速入门。本节是详细版本:介绍其他启动方式、预期情况以及 Flisk 会写入的内容。若从未使用过终端,请改为从这里开始。
选择启动方式
有 4 种方式可以让应用运行:最简单的方式、一条命令启动演示、手动设置项目,以及通过引导式设置回答问题。最简单的方式如下;每个标签页都会打开自己的页面。
|
只需一条命令,就能在自己的电脑上运行应用,无需 Docker。这种方式适用于由几个组件组成的应用,每个组件都通过一条命令启动,例如后端(API)、网站和工作进程。你只需要 Flisk 和运行代码的程序,例如 Node.js。 面向开发者: 每项服务都作为本地进程运行。你只需要 Flisk 和应用的运行时。 1. 安装 Flisk。 将以下内容粘贴到终端中,然后按 Enter:
2. 描述各个组件。 在每个组件的文件夹中(每项服务旁边)放置一个名为
这是网站的配置。
3. 启动所有组件。 在终端中进入项目文件夹并运行:
你会看到:Flisk 启动 API,等待它响应,然后启动网站。它会打印两个 URL(可在浏览器中打开的网址;这些是 localhost 链接,因此只有你能看到)。每行输出都以生成它的组件名称开头。如果某个组件崩溃,Flisk 会重新启动它。 要停止运行,请按 Ctrl+C(按住 Control 并按 C),或运行 |
验证是否正常运行
对于本页顶部的 shop,flisk up shop 会先列出它将启动的内容及其位置:
Starting 2 services from stack "shop"...
- orders-api
- shop-web
🌍 Frontend URLs:
- shop-web: http://app.my-shop.localhost/shop-web/health
🔧 Backend API URLs:
- orders-api: http://api.my-shop.localhost/api/orders/health
Host ports: HTTP 80, HTTPS 443, Postgres 15432
然后 Tilt 会构建并启动容器,flisk up 最后会显示 Flisk is up. 和 Tilt 控制面板地址 http://localhost:10350;每项服务在运行正常时都会变为绿色。主机端口可能有所不同:如果 80 或 5432 端口正忙,Flisk 会选择一个空闲端口,并在 URL 中包含该端口。flisk down 会停止所有内容。接下来你会用到的所有命令都列在命令下。
故障排查
| 问题 | 修复方法 |
|---|---|
flisk doctor 失败 | 执行它打印的修复命令,然后重试 |
| 端口 80/5432 已被占用 | flisk doctor 会显示占用进程;停止该进程或设置 FLISK_HTTP_PORT |
| Docker 未运行 | 启动 Docker Desktop / systemctl start docker |
| Windows 原生环境 | 使用 WSL2 Ubuntu;参阅 Windows 指南 |
flisk up 拒绝启动 | 先运行 flisk doctor;它会说明缺少什么 |
完整故障排查指南:docs/troubleshooting.md
运行 flisk up --verbose 前设置 FLISK_DEBUG=1,即可在 Tilt 输出中包含 Starlark 调试日志。
Flisk 会为你生成的内容
每个服务只需编写一个 service.json。对于上面的双服务商店,Flisk 会在三个层级生成其余内容:项目、堆栈和各个服务。
my-shop/
├── .env # generated DB_PASSWORD and JWT_SECRET
├── .flisk/
│ ├── project.json # project settings (yours to edit)
│ └── .flisk-out/ # PROJECT LEVEL
│ ├── Tiltfile # what Tilt runs
│ ├── docker-compose.traefik.yml # local gateway, bound to 127.0.0.1
│ ├── golden-layers.Dockerfile # shared base image layers
│ ├── TILT_TECH_STACK.star # tech stack settings
│ ├── TILT_RESOURCE_DEFAULTS.star # service defaults
│ ├── spec.master # project spec by stack
│ └── flisk-cli-ext/ # pinned copy of the Flisk engine
├── shared-platform-engineering/
│ └── docker-templates/ # container entrypoint scripts
└── services/
├── platform/database-management/
│ └── docker-compose.yml # Postgres 16
└── shop/
├── .autogenerated/ # STACK LEVEL
│ └── docker-compose.app.autogenerated.yml # every service in the stack
├── orders-api/
│ ├── service.json # you write this
│ └── .autogenerated/ # SERVICE LEVEL: 14 files
└── shop-web/
├── service.json # you write this
└── .autogenerated/ # SERVICE LEVEL: 18 files
堆栈的 Compose 文件是你原本需要手动编写的部分。对于这两个服务,它包含镜像构建配置、环境变量、33 个 Traefik 路由标签、四个网络、健康检查,以及 CPU 和内存限制。摘录如下:
orders-api:
environment:
- DATABASE_URL=postgresql://my_shop:${DB_PASSWORD}@my_shop_postgres:5432/my_shop_shop?schema=public
- JWT_SECRET=${JWT_SECRET:?JWT_SECRET is not set. Run `flisk up` ...}
labels:
- "traefik.http.routers.orders-api-project.rule=Host(`api.my-shop.localhost`) && PathPrefix(`/api/orders`)"
- "traefik.http.middlewares.orders-api-strip-prefix-project.stripprefix.prefixes=/api/orders"
- "traefik.http.services.orders-api.loadbalancer.healthcheck.path=/health"
healthcheck:
test: ["CMD", "curl", "-f", "--max-time", "5", "http://localhost:4000/health"]
默认情况下,密钥来自项目的 .env 文件:flisk project 会生成随机数据库密码和 JWT 密钥,并将 .env 添加到 .gitignore。设置 FLISK_SECRET_PROVIDER=infisical,即可改为从 Infisical 读取密钥(环境配置)。
每个服务的 .autogenerated/ 文件夹中的所有文件
shop-web/.autogenerated/
├── Dockerfile.app.autogenerated # app image
├── Dockerfile.app.autogenerated.dockerignore # build context
├── nginx.autogenerated.conf # serves the build, routes API requests
├── vite.config.frontend.autogenerated.ts # dev server
├── vite.config.build.autogenerated.ts # production build
├── tsconfig.autogenerated.json # TypeScript, host
├── tsconfig.docker.autogenerated.json # TypeScript, container
├── .npmrc.autogenerated # package registry, host
├── .npmrc.docker.autogenerated # package registry, container
├── bunfig.autogenerated.toml # Bun settings, host
├── bunfig.docker.autogenerated.toml # Bun settings, container
├── .env.frontend.autogenerated # frontend environment
├── env.ts # API URL for your imports
├── api-client.ts # client for the frontend's API route
├── api-index.ts # re-exports the client and URL
├── service.yaml # Tilt's projection of service.json
├── validation-report.autogenerated.json # preflight validation result
├── AGENTS.md # tells coding agents not to edit here
└── .flisk-contract/ # snapshots for drift checks
orders-api/.autogenerated/
├── Dockerfile.app.autogenerated # app image
├── Dockerfile.app.autogenerated.dockerignore # build context
├── vite.config.backend.autogenerated.ts # server build
├── prisma.config.autogenerated.ts # database client
├── tsconfig.autogenerated.json # TypeScript, host
├── tsconfig.docker.autogenerated.json # TypeScript, container
├── .npmrc.autogenerated # package registry, host
├── .npmrc.docker.autogenerated # package registry, container
├── bunfig.autogenerated.toml # Bun settings, host
├── bunfig.docker.autogenerated.toml # Bun settings, container
├── .env.backend.autogenerated # backend environment
├── service.yaml # Tilt's projection of service.json
├── validation-report.autogenerated.json # preflight validation result
├── AGENTS.md # tells coding agents not to edit here
└── .flisk-contract/ # snapshots for drift checks
包含数据库迁移器的堆栈还会在堆栈文件夹中生成 docker-compose.migrator.autogenerated.yml,迁移器也会有自己的 Dockerfile.migrator.autogenerated。
你无需为此堆栈编写 nginx 配置、Dockerfile、Compose 文件或 Traefik 标签。flisk up 会在 service.json 变更时重新生成这些文件;如果检测到文件被手动编辑,则会拒绝启动。Python、Go 和 Rust 服务以及 Playwright 等可选功能也有各自的文件集合;生成文件指南列出了这些文件,并说明了漂移检查。
另请参阅 Flisk 与替代开发工具的比较、Flisk CLI 如何与 Helm 配合使用、服务架构和项目配置架构。
命令
日常会用到的命令:
| 你想要 | Flisk 会执行 | 命令 |
|---|---|---|
| 启动新项目 | 创建项目和首批服务 | flisk project --yes |
| 添加服务 | 写入其 service.json 和生成文件 | flisk resource <name> --type backend --stack <stack> --yes |
| 启动整个堆栈 | 启动 Postgres、你的服务和路由,并打印 URL | flisk up <stack> |
| 启动前预览 | 显示将要启动的服务和 URL,不启动容器 | flisk up <stack> --dry-run |
| 检查运行中的服务 | 打开交互式终端仪表板 | flisk ui |
| 检查你的计算机 | 报告 Docker、Tilt 和端口的就绪状态 | flisk doctor |
| 检查配置漂移 | 将生成文件与 Flisk 上次写入的文件进行比较 | flisk config verify |
| 查看某个服务的日志 | 打印该服务最近的日志行 | flisk logs --service <name> |
| 重启某个服务 | 在运行中的堆栈内重启该服务 | flisk restart <name> |
| 停止所有内容 | 停止堆栈中的每个服务 | flisk down |
| 保持 Flisk 为最新版本 | 原地升级 CLI | flisk upgrade |
命令支持 --help;--json 会为脚本和 Agent 打印一个 JSON 对象(机器可读输出)。通过 flisk mcp,这些操作也可作为 MCP 工具使用。所有命令和标志:速查表。
Flisk 支持:
- 运行时与框架: Bun、Node、Python、Go、Rust、React、Vue、Svelte、Elysia、Fastify、NestJS
- 数据库与工具: Prisma、Drizzle、Atlas、Dbmate
- 消息传递与网关: NATS、Traefik
配置
你需要编辑三类文件;Flisk 会写入其他所有文件,并检查是否有人手动修改。
| 文件 | 内容 | 参考 |
|---|---|---|
service.json,每个服务一个 | 名称、类型、技术栈、端口、健康检查、dependsOn、用于将服务作为本地进程运行的 command,以及可选功能 | 所有字段 |
.flisk/project.json | 项目名称,以及每个阶段启用哪些技术栈;flisk project 会创建此文件 | 项目设置 |
.env | DB_PASSWORD 和 JWT_SECRET 等机密;flisk project 会生成这些变量,并将 .env 添加到 .gitignore | 环境 |
Flisk 会从有界备用范围中为 HTTP、HTTPS 和 Postgres 选择主机端口;开发端口只监听 127.0.0.1,因此网络中的其他设备无法访问。这些环境变量可更改此设置及其他选项:
| 变量 | 作用 |
|---|---|
FLISK_HTTP_PORT、FLISK_HTTPS_PORT、FLISK_POSTGRES_PORT | 固定网关(HTTP、HTTPS)或 Postgres 的主机端口 |
FLISK_BIND_ADDRESS | 开发端口监听的地址,默认为 127.0.0.1。0.0.0.0 可让你通过手机测试;当地址为通配地址时,flisk doctor 会发出警告 |
FLISK_SECRET_PROVIDER | infisical 会从 Infisical 读取机密,而非从 .env 读取 |
TILT_PORT | Tilt UI 端口,默认为 10350 |
FLISK_DEBUG | 设为 1 并使用 flisk up --verbose,会将 Starlark 调试日志添加到 Tilt 输出中 |
两个 JSON 文件的编辑器自动补全和验证:配置和编辑器架构。
Flisk 的工作原理
- 描述每个服务:在代码旁边放置一个
service.json。 - 运行
flisk up <stack>。 Flisk 根据这些清单生成本地运行时文件:Dockerfile、Traefik 路由和 Tiltfile。 - Docker 运行容器,Tilt 负责监视。 编辑代码,容器会实时更新。使用
flisk ui检查正在运行的服务,并使用flisk doctor或flisk config verify检查环境和生成的文件。
所有内容都会自动连通并保持同步
你无需手动连接服务。Flisk 会根据同一批 service.json 文件推导各项连接,并在文件变更时重新生成配置。
| 当你…… | Flisk 会更新 |
|---|---|
使用 flisk resource 添加服务 | 系统会自动发现该服务,并在下次运行 flisk up 时启用其技术栈。Flisk 会为它生成镜像构建配置、Compose 条目、网关路由、健康检查及专属的 .autogenerated/ 文件。 |
编辑 service.json(端口、dependsOn、功能) | 下次运行 flisk up 时,会重新生成 Dockerfile、Compose 条目、Traefik 标签和 nginx 配置。生成文件中的手动修改会在启动任何内容之前被检测为配置漂移。 |
| 编辑代码 | Tilt 会实时更新正在运行的容器。无需重新构建。 |
| 添加后端路由 | 前端已通过生成的 VITE_API_URL、env.ts 和 api-client.ts 指向 API;这些配置基于网关路由使用的相同主机名生成。 |
| 添加数据库或第二个后端 | DATABASE_URL 和其他连接设置会注入每个服务的环境中。无需复制密码或主机名。 |
在 .env 较旧或缺失的项目中运行 | 会生成 JWT_SECRET 等缺失的机密,同时不会覆盖你已有的值。 |
声明 dependsOn | 服务会按照通过健康检查的顺序启动。 |
完整启动流程请参阅 flisk up 的工作原理。
为什么选择 Flisk CLI?
Flisk 在 10 个类别中与另外两款工具进行比较。选择一个标签页:
Docker Compose 和 Tilt 是开发者用来在自己的计算机上启动应用各个部分的工具。Compose 会根据你编写的 YAML 设置文件运行容器。Tilt 会监视你的文件,并在你保存文件时实时更新正在运行的应用;它使用你编写的 Tiltfile。Flisk 会根据每个服务(应用的每个部分)对应的一个小型 service.json 文件,为你生成这两个文件,然后运行 Tilt。
| Docker Compose | Tilt | Flisk | |
|---|---|---|---|
| 用一条命令搭建新服务 | 部分支持(docker init 会生成 Dockerfile 和 Compose 文件) | 不支持 | 支持(flisk resource) |
| 文件更改时热重载 | 部分支持(compose watch) | 支持(live_update) | 支持(生成的 Tilt live_update) |
| 按健康检查结果控制启动顺序 | 支持(depends_on: condition: service_healthy) | 支持(手动编写 resource_deps) | 支持(根据 dependsOn) |
| 每个服务都有网关 URL,并包含 Postgres | 不支持(需自行添加) | 不支持(需自行添加) | 支持(Traefik *.localhost 和 Postgres) |
| 启动大型系统中的一个堆栈 | 部分支持(profiles) | 支持(tilt up <resource>) | 支持(flisk up <stack>) |
| 需要手动编写的配置 | compose.yaml | Tiltfile(Starlark) | 仅需 service.json;其余内容均自动生成并检查偏差 |
它们的优势
- Compose 更适合已经容器化的两三个服务,且无需使用 Tilt。
- Tilt 适合希望自行编写和维护 Tiltfile、并需要完全控制的场景,同时也支持 Kubernetes。
可组合使用。 Flisk 会生成 Compose 文件和 Tiltfile,并通过 Docker 和 Tilt 运行它们;使用 flisk config explain 可以清晰查看生成的文件。
有关架构权衡、各工具更适用的场景以及迁移工作流,请参阅详细的工具比较。
示例
可运行的示例展示 Flisk 在真实技术栈中的用法。先从最小的示例开始:
| 示例 | 展示内容 |
|---|---|
| one-backend | 使用 Postgres 的单个 Bun/TypeScript 后端 |
| one-backend-python | 同一套本地技术栈中的 Python 后端 |
| one-backend-helm | 与 Helm 协同工作 |
| byo | 使用你已有的资源 |
| byo-jobs | 使用自有任务 |
| flisk-example | 完整的多服务技术栈 |
何时不应使用 Flisk
- 你现有的 Compose 或 Tilt 工作流已经能提供可用的本地环境。
- Helm 就是你的整个开发工作流,而且你不想在 Docker 上运行本地服务。
- 你不想使用
service.json清单和生成的本地配置。
要求与支持
对于 Docker + Tilt 方案,请安装 Docker(Desktop、OrbStack 或 Colima;Engine 25+、Compose 2.20.2+)和 Tilt。默认生成的服务使用 Bun 1.2+。端口和其他设置请参阅:Configuration。
Flisk 支持 macOS、Linux,以及通过 WSL2 Ubuntu 运行的 Windows。原生 Windows 仅支持检查操作:flisk --version、flisk doctor 和 flisk up --dry-run 可以运行,而 flisk up 会以状态码 1 退出,并显示“Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”。请参阅 Windows & WSL2 guide,了解推荐的设置、先决条件、验证步骤和故障排查。
路线图
未来 12 个月,Flisk 计划保持 1.x 稳定(flisk up、脚手架、生成的文件和 flisk config verify 将保持向后兼容),保持核心免费,继续支持 Windows 和 WSL2,持续强化供应链安全,保持文档更新,并增加维护者。Flisk 不计划部署到生产环境,也不计划支持 Kubernetes。完整计划及如何提议变更,请参阅:ROADMAP.md。
许可证矩阵
| 功能 | 免费版 | 高级版 |
|---|---|---|
flisk up、脚手架、Traefik、Postgres、Tilt 实时更新、黄金层 | 是 | 是 |
| Verdaccio、DDD 脚手架、Sablier 空闲停止 | 否 | 密钥 |
| Playwright、C4、AGENTS.md | 在仓库内生成时免费 | 仅当使用密钥下载实现时提供 |
核心始终免费。高级版需要单独的密钥才能使用上述额外功能;运行 flisk up 无需密钥。
稳定性:1.x。
常见问题
我从没写过代码。Flisk 适合我吗?
如果你会使用 Claude Code、Codex 或 Cursor 这样的 AI 助手来构建应用,那就适合。你描述应用的需求;助手会编写代码,并使用 Flisk 在你的电脑上运行应用。从这里开始 会逐步引导你完成操作,而 你会看到的术语 会解释相关术语。你需要在终端中粘贴几条命令,但不需要编写任何代码。
需要付费吗?
Flisk 命令行工具免费且开源(MIT);可选的 Premium 附加功能需要密钥(请参阅许可证矩阵)。你的 AI 助手有自己的方案和价格。规模较大的应用还会用到 Docker Desktop,个人和小型公司可免费使用。
我需要 Kubernetes 吗?
不需要。Flisk 会在你的电脑上使用 Docker 和 Tilt 运行服务。它不需要 kind 或 minikube 之类的本地集群,也不会取代 Helm、Compose 或你的生产部署工具。
我需要许可证密钥吗?
不需要。核心 CLI 采用 MIT 许可证,运行 flisk up 不需要密钥。Premium 附加功能是可选的,使用单独的密钥(请参阅许可证矩阵)。
支持哪些平台?
macOS 和 Linux 均可直接使用。Windows 通过 WSL2 Ubuntu 获得支持;原生 Windows 仅支持 CLI 检查(flisk --version、flisk doctor、flisk up --dry-run)。请参阅要求和支持以及 Windows 和 WSL2 指南,了解推荐的设置、先决条件、验证步骤和故障排除方法。
Flisk 会把我的代码发送到其他地方吗?
Flisk 会在你的电脑上运行本地技术栈。有关网络调用、密钥和供应链的详情,请参阅安全:网络调用、密钥和供应链。
我可以继续使用 Compose、Helm 或自己的 Tilt 设置吗?
可以。如果你现有的设置已经能提供可用的本地环境,就继续使用它。请参阅与 Helm 协同工作和渐进式采用,了解如何在现有代码仓库中添加 Flisk。
遇到 Bug 时该怎么办?
请先更新;最近发布的版本可能已经修复了问题。运行 flisk upgrade(也可以使用 flisk update),或者:
npm install -g @flisk-sh/flisk@latest
然后运行 flisk doctor,并重试相同的任务。如果问题仍然存在,请提交问题,并附上 Flisk 版本、操作系统、重现步骤和错误输出。请参阅升级和固定版本以及故障排除。
- Flisk 101:面向初学者的 13 个实验课程
- CLI 命令速查表
- 超级速查表:所有命令和标志
- 文档索引
- 在真实代码仓库中试用 Flisk
- 在 Flisk 中运行 AI Agent
- 面向代理机构和多客户端团队的常见问题
- 与 Helm 协同工作
- 范围:本地开发,以及哪些内容不会延续到生产环境
- 逐步采用:将 Flisk 添加到现有代码仓库
- 故障排除:flisk 和 Tilt 错误消息及其解决方法
- 布局与所有权:多个代码仓库中的服务
- 本地数据:重置、填充、快照
- 升级和版本固定
- 安全性:网络调用、机密信息和供应链
- 试点评分表
- 自带资源
- 配置和编辑器架构
- 生成的服务文件和漂移检查
- 可运行的单后端示例
- 可运行的 Python 后端示例
- 完整的多服务示例
- 功能和许可证限制
- 工具对比:docker-compose、Tilt、Skaffold、DevSpace、kind
- 坦诚的对比和已知限制
- 公开声明登记表
- 一键开始:托管启动模板和部署提示词
- 项目历史
- 架构和代码仓库概览
- 规模测试夹具测量结果和注意事项
- 基准测试报告:热启动和冷启动图表及历史记录(每次对
main中影响启动的内容进行更改后更新) - 如何运行启动时间基准测试
社区
生态地图: 示例、文章、相关工具和笔记都收录在 awesome-flisk-framework 中。如果你使用 CLI,请为此仓库(flisk)点个 Star;想浏览其他内容,可以查看 awesome 列表。如果 Flisk 为你节省了时间,请在此仓库点个 ⭐,帮助其他开发者发现它。
分享: X · Bluesky · Threads · Mastodon · Reddit · Hacker News · Facebook · LinkedIn · Telegram · WhatsApp · Email
贡献与许可证
欢迎贡献。第一步:在 Discord 上打个招呼,告诉我们你想参与什么,我们会为你推荐一个适合入门的任务。然后从 CONTRIBUTING.md 和贡献者指南开始。有关项目结构,请参阅架构和仓库地图。如需审查拉取请求,请参阅审查拉取请求。请通过 SECURITY.md 报告安全问题。
测试、扩展能力和安全状态
ERP 测试夹具扩展测试在全新的 GitHub 托管运行器(4 vCPU,15 GB RAM)上执行,数据快照来自运行记录 39160719471。实时状态请见上方的 ERP 测试夹具扩展 E2E 徽章。
贡献者
感谢自 2026 年 7 月以来为 Flisk 提交代码、文档和修复的每一位贡献者。每个合并的改动,都让后续开发者使用本地技术栈时更加顺畅。
Flisk 采用 MIT 许可证;详见 LICENSE。许可证边界说明了哪些代码采用 MIT 许可证,哪些代码需要使用密钥下载。
项目治理:GOVERNANCE.md、MAINTAINERS.md、ADOPTERS.md。
在 Slack 或 Discord 中使用 Flisk?获取 Flisk 绿色闪电表情(SVG 和 PNG,采用 MIT 许可证)。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。








































