mcpField
F
Flisk

Flisk

本地服务
flisk.sh开发工具28今天更新

关于 Flisk

Flisk 是用于本地运行应用服务的命令行工具,服务配置来自 service.json。它生成并跟踪开发环境文件,支持热重载,也可为 Agent 提供管理 Flisk 项目的 MCP 服务。

主要功能

  1. 01根据 service.json 生成开发文件
  2. 02通过本地网关启动服务
  3. 03文件变更时重新加载服务
  4. 04配置服务 URL 和环境变量
  5. 05检查生成文件的偏差
  6. 06通过检查点和路由运行 Agent 服务

适用场景

  1. 01在本地启动多服务应用
  2. 02导入现有 Compose 项目
  3. 03为 Agent 提供管理服务栈的工具
  4. 04让 Agent 与其工具及数据库共同运行

MCP 相关

`flisk mcp` 通过 stdio 运行 MCP 服务,并向 Agent 提供 21 个工具。`flisk connect` 可为受支持的 Agent 添加服务配置。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"flisk-sh-flisk": {
"command": "npx",
"args": [
"-y",
"@flisk-sh/flisk"
]
}
}
}
启动命令npx -y @flisk-sh/flisk

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npm@flisk-sh/flisk1.4.17

工具

21

收录的工具列表 · 更新于 今天

参数类型必填说明
noPingboolean否跳过对运行中服务的健康检查端点执行 ping
projectPathstring否Flisk 项目根目录的绝对路径;从该目录运行此操作。

详细介绍

什么是 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 命令创建项目、API 和网站,然后启动它们

每个服务只需一个小文件

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 顺序启动服务,并为每个服务打印一个 *.localhost URL。
  • 编码时热重载。 保存文件时,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. 这个应用是用什么编写的?
JavaScript / TypeScript(已选)PythonGoJava / KotlinRuby / PHP其他 / 不确定
2. 开发者现在如何在笔记本电脑上启动应用?
Kubernetes脚本 + wikiDocker Compose(已选)Tilt 或 SkaffoldDocker 应用Dev Containers在浏览器中直接运行代码其他 / 不确定
3. 这个应用由多少个部分组成?(网站、API、后台任务……)
只有一个2–4 个部分5 个或更多(已选)

契合度 82%:非常适合

非常适合。 Flisk 正是为你这样的团队打造的。为什么是这个分数 → · 在 flisk.sh 上使用完整计算器

信赖 Flisk 的团队

LekastMFin ServicesMakeOfferRedMoon.Digital

这些团队在自己的代码上运行 flisk up,并已同意列出。查看所有采用者,或添加你的团队。

将 Flisk 与你的 AI Agent 搭配使用

AI 助手擅长编写应用,却不擅长处理周边的配置:每次它手动重写 Dockerfile、Tiltfile 或 nginx.conf,总会出问题,你还得花时间和 token 修复。Flisk 每次都会用同样的方式生成这些配置,让你和助手专注于应用本身。

Claude Code 在 Warp 终端中运行,借助 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.
### 选择你的 Agent

每种助手的安装方式略有不同;选择你的助手,查看具体步骤。已有项目?运行 flisk connect claude(或 cursor、codex),即可添加 flisk mcp 服务(21 个工具)和 Flisk 技能,安装到该 Agent 读取技能的位置;添加 --dry-run 可先查看文件。Agent 随后能做什么:面向 AI Agent 的 Flisk。

终端中的 Claude Code,~/my-shop
Claude Code(已选中)CodexCursor3 个 Agent
curl -fsSL https://claude.ai/install.sh | bash
npm install -g @flisk-sh/flisk

然后在项目文件夹中输入 claude 启动 Claude Code,并粘贴上面的提示词。开发者注意:flisk project 会将 Flisk 技能写入 .claude/skills/,Claude Code 会从中加载技能。若要让 Claude Code 通过 MCP 工具驱动 Flisk,请运行 claude mcp add --scope project flisk -- flisk mcp。Windows 安装、.mcp.json 文件和 AGENTS.md 使用提示,请参阅:Claude Code 完整设置指南。

Claude Code 输入:为我搭建一个小型网店,包含店面和订单 API…

任何能够运行终端命令的其他 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.js22.12+nodejs.orgnpm 安装(npm install -g @flisk-sh/flisk)
DockerEngine 25+,Compose 2.20.2+docker.com仅用于 Docker + Tilt 方式
Tilt0.25+curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash仅用于 Docker + Tilt 方式
Bun1.2+curl -fsSL https://bun.sh/install | bashBun 安装(bun add -g @flisk-sh/flisk),或生成 JavaScript 服务

两种运行方式。 如果项目中的每项服务都声明了 command,Flisk 会将它们作为本地进程运行:只需要 Flisk 和应用所用的运行时(最简单的方式)。如果需要数据库、供所有服务共用的网关 URL,或与部署时相同的容器,则需要 Docker 和 Tilt。flisk doctor 只会检查项目实际使用的内容。

设置你的电脑。选择系统:

macOS 窗口:flisk up — ~/my-shop
macOS(已选中)UbuntuWindows(WSL2)Omarchy4 个系统

只需一次即可完成 Mac 的准备工作。将每个灰色框中的内容粘贴到终端(按下 Cmd+Space,输入 Terminal,然后按 Enter),再按 Enter。

1. 安装 Node.js 22.12+,从 nodejs.org 获取;如果应用使用的不是 JavaScript,还需安装应用所用的语言。小型应用只需这些:最简单的方式。

2. 仅适用于较大型的应用(需要数据库、让所有部分共用一个地址,或使用与部署时相同的容器):启动 Docker Desktop、OrbStack 或 Colima,并安装 Tilt:

curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \
  | bash

3. 安装 Flisk 并检查 Mac:

npm install -g @flisk-sh/flisk
flisk doctor

flisk doctor 只会检查项目实际使用的内容,并为缺少的项目打印修复方法。完整步骤:macOS 设置。

2 项服务运行正常,耗时 0.8 秒 · 无 Docker · Apple M1 · 16 GB · flisk 1.4.7
## 安装

可通过 npm、Bun 或预构建二进制文件安装 CLI,无需 Node.js 或 Bun:

npm (selected)BunPrebuilt binary3 ways to install
npm install -g @flisk-sh/flisk

这会通过 npm 下载 Flisk,npm 随附 Node.js 22.12+。使用 flisk --version 检查:它会显示版本号。之后可使用 flisk upgrade 更新。固定版本和卸载方法请参阅:通过 npm 安装。

**面向开发者:**推荐默认使用公共 npm;如需改用 GitHub Packages 安装,请按GitHub Packages 安装说明配置注册表身份验证。

之后可使用 flisk upgrade(或其别名 flisk update)更新,也可运行 npm install -g @flisk-sh/flisk@latest。如需固定版本或查看变更内容,请参阅升级和固定版本。

重要

请从 flisk-sh/flisk 仓库、 @flisk-sh/flisk npm 包或 官方网站获取 Flisk。请通过这些官方来源中的安装链接进行安装。 仓库名称相似或 README 被复制,都不能证明下载内容是官方的。

快速开始

准备好先决条件(安装一次即可)后,Flisk 是什么?下的命令就是完整的快速入门。本节是详细版本:介绍其他启动方式、预期情况以及 Flisk 会写入的内容。若从未使用过终端,请改为从这里开始。

选择启动方式

有 4 种方式可以让应用运行:最简单的方式、一条命令启动演示、手动设置项目,以及通过引导式设置回答问题。最简单的方式如下;每个标签页都会打开自己的页面。

最简单(已选中)一条命令启动演示完全掌控引导式设置4 种启动方式

只需一条命令,就能在自己的电脑上运行应用,无需 Docker。这种方式适用于由几个组件组成的应用,每个组件都通过一条命令启动,例如后端(API)、网站和工作进程。你只需要 Flisk 和运行代码的程序,例如 Node.js。

面向开发者: 每项服务都作为本地进程运行。你只需要 Flisk 和应用的运行时。

1. 安装 Flisk。 将以下内容粘贴到终端中,然后按 Enter:

npm install -g @flisk-sh/flisk

2. 描述各个组件。 在每个组件的文件夹中(每项服务旁边)放置一个名为 service.json 的小型设置文件。它会告诉 Flisk 组件的名称、启动组件的命令,以及它监听的端口。这是后端的配置:

{
  "schemaVersion": 1,
  "appName": "api",
  "appType": "backend",
  "command": "node server.js",
  "port": 4000,
  "healthCheckPath": "/health"
}

这是网站的配置。"dependsOn": ["api"] 表示“先启动后端”:

{
  "schemaVersion": 1,
  "appName": "web",
  "appType": "frontend",
  "command": "node server.js",
  "port": 3000,
  "dependsOn": ["api"]
}

3. 启动所有组件。 在终端中进入项目文件夹并运行:

flisk up

你会看到:Flisk 启动 API,等待它响应,然后启动网站。它会打印两个 URL(可在浏览器中打开的网址;这些是 localhost 链接,因此只有你能看到)。每行输出都以生成它的组件名称开头。如果某个组件崩溃,Flisk 会重新启动它。

要停止运行,请按 Ctrl+C(按住 Control 并按 C),或运行 flisk down。无需 Docker、Tilt,也不会生成文件。有关每个字段的说明,以及何时切换到包含数据库和一个网关 URL(所有组件共用的一个网址)的完整技术栈,请参阅无需 Docker 运行应用。

验证是否正常运行

对于本页顶部的 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、你的服务和路由,并打印 URLflisk 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 为最新版本原地升级 CLIflisk 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 会创建此文件项目设置
.envDB_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_PROVIDERinfisical 会从 Infisical 读取机密,而非从 .env 读取
TILT_PORTTilt UI 端口,默认为 10350
FLISK_DEBUG设为 1 并使用 flisk up --verbose,会将 Starlark 调试日志添加到 Tilt 输出中

两个 JSON 文件的编辑器自动补全和验证:配置和编辑器架构。

Flisk 的工作原理

  1. 描述每个服务:在代码旁边放置一个 service.json。
  2. 运行 flisk up <stack>。 Flisk 根据这些清单生成本地运行时文件:Dockerfile、Traefik 路由和 Tiltfile。
  3. 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 个类别中与另外两款工具进行比较。选择一个标签页:

Compose 与 Tilt(已选中)Kubernetes 开发循环本地集群进程运行器开发环境云工作区应用框架单体仓库工具集群桥接工具AI Agent10 项比较

Docker Compose 和 Tilt 是开发者用来在自己的计算机上启动应用各个部分的工具。Compose 会根据你编写的 YAML 设置文件运行容器。Tilt 会监视你的文件,并在你保存文件时实时更新正在运行的应用;它使用你编写的 Tiltfile。Flisk 会根据每个服务(应用的每个部分)对应的一个小型 service.json 文件,为你生成这两个文件,然后运行 Tilt。

Docker ComposeTiltFlisk
用一条命令搭建新服务部分支持(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.yamlTiltfile(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 on Product Hunt flisk-sh%2Fflisk | Trendshift

生态地图: 示例、文章、相关工具和笔记都收录在 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 报告安全问题。

测试、扩展能力和安全状态

Journeys E2E ERP fixture scale E2E Example apps E2E CodeQL OpenSSF Scorecard 已知漏洞 Socket 徽章

ERP 后端健康状况 ERP 全部健康所需时间 ERP 前端响应情况 ERP 运行中的容器 ERP 内存使用量 测试覆盖率

ERP 测试夹具扩展测试在全新的 GitHub 托管运行器(4 vCPU,15 GB RAM)上执行,数据快照来自运行记录 39160719471。实时状态请见上方的 ERP 测试夹具扩展 E2E 徽章。

解包大小 安装大小 OSS Insight X 粉丝:1,605

OpenSSF 最佳实践 OpenSSF 银级:95%

贡献者

感谢自 2026 年 7 月以来为 Flisk 提交代码、文档和修复的每一位贡献者。每个合并的改动,都让后续开发者使用本地技术栈时更加顺畅。

kburym
kburym
odykyi
odykyi
sb123sb123
sb123sb123
AK-Lmn
AK-Lmn
yoreva-01
yoreva-01
minutechreview
minutechreview
Delfi2007
Delfi2007
Ghifariezra
Ghifariezra
Huang-404-Q
Huang-404-Q
dbdefault
dbdefault
Rohith-Saran
Rohith-Saran
aazminu
aazminu
xiehuanyi
xiehuanyi
NimoCao
NimoCao
rahul05ranjan
rahul05ranjan
krishna2707
krishna2707
arxh80
arxh80
tnalbant
tnalbant
sunny-kavixo
sunny-kavixo
sohammkk
sohammkk
sinhaananya812-star
sinhaananya812-star
jay23606
jay23606
floatyserve
floatyserve
eddyflores100-lang
eddyflores100-lang
denisvmedia
denisvmedia
amritkang165
amritkang165
airdropia
airdropia
adity982
adity982
YuuGR1337
YuuGR1337
WilsonSoetomo
WilsonSoetomo
Vignesh2662006
Vignesh2662006
Samueldavidddsc
Samueldavidddsc
Murphyvon
Murphyvon
KeuqS
KeuqS
Golden007-prog
Golden007-prog
GeoCeff
GeoCeff
Enard52
Enard52

Flisk 采用 MIT 许可证;详见 LICENSE。许可证边界说明了哪些代码采用 MIT 许可证,哪些代码需要使用密钥下载。

项目治理:GOVERNANCE.md、MAINTAINERS.md、ADOPTERS.md。

flisk 在 Slack 或 Discord 中使用 Flisk?获取 Flisk 绿色闪电表情(SVG 和 PNG,采用 MIT 许可证)。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。