create-windy

create-windy

创建一个以 Bun、Vue 3、Elysia、Drizzle 和 PostgreSQL 为基础的 Windy 企业 Dashboard Starter。生成结果将用户功能层与 /admin/** 平台控制面分开，适合 单组织、单租户、私有部署优先的项目。

创建项目

npm create windy@latest my-dashboard

也可以使用同一个 npm 包：

npx create-windy@latest my-dashboard
bun create windy my-dashboard
yarn dlx create-windy@latest my-dashboard
pnpm dlx create-windy@latest my-dashboard

这些入口只负责下载同一个 npm artifact；安装出的 create-windy bin 固定由 Bun 执行，本机需要 Bun 1.3.14 或更高版本。生成项目也固定使用 Bun。创建器默认安装依赖、 初始化 Git main 分支并尝试创建 chore: initialize project 首次提交。

不带参数运行时会在同一个列表中交互选择平台模块和 Oxc 基础设施，再选择项目法律 许可证。列表中的括号展示用途说明，不暴露内部模块 Key；使用上下键移动、空格切换 选中状态、回车提交选择。CI 或脚本中可使用：

# 接受默认模块、Oxc 和 UNLICENSED
npm create windy@latest my-dashboard -- --yes

# 只保留 system 与 system.identity
npx create-windy@latest my-dashboard --no-optional-modules

# 显式增加模块；--module 可重复
npx create-windy@latest my-dashboard \
  --module system.storage \
  --module work-order

# 选择全部已注册模块
npx create-windy@latest my-dashboard --all-modules

# 不引入 Oxlint/Oxfmt
npx create-windy@latest my-dashboard --no-oxc

# 生成 MIT 法律许可证；Apache-2.0 同样受支持
npx create-windy@latest my-dashboard \
  --license MIT \
  --license-holder "Your Name"

默认选择

• 锁定核心：system、system.identity。
• 默认模块：system.settings、system.configuration、system.audit、 system.operations。
• 默认不选：离线 system.license、文件、任务、通知、工作流、搜索、数据治理、 Agent、批量数据和示例工单等模块。
• 默认代码质量：Oxlint + Oxfmt。Husky 会在提交前通过 lint-staged 自动格式化并检查暂存 文件，不会把未暂存内容带入提交；lint、typecheck 和 test 保留为显式命令。
• --no-oxc 会物理排除 Oxc 配置、Husky hook、lint-staged、依赖和质量脚本。
• 默认法律许可证：UNLICENSED，不会生成 LICENSE 文件。

法律许可证与离线 system.license 是两项独立选择：前者决定项目代码授权，后者 为离线部署提供运行时验签与限制态。

选择 system.license 时，Server 与 Web 通过 npm 依赖 @southwind-ai/license@^0.1.9 使用运行时能力；生成项目及 create-windy 模板快照都 不包含 packages/license-sdk 源码。发布包含该模块的新版创建器前，必须先确认目标 registry 中存在该版本，并完成真实安装回归。

未选择或未配置 License 时，产品功能走明确的 free/no-license 路径，License 版本、 Entitlement 和限制态不阻断功能；Feature 与 RBAC 仍照常执行。已生成模块在 registry 中禁用时，声明的 License runtime API Route 仍保留，但统一 Manifest Guard 返回 403 feature-disabled。只有模块和配置都启用后，最终授权才由 Server 后端执行；限制态仅 为显式 License 恢复入口保留窄 admin-admission 例外，Admin 普通开关不能自行放行。

未选择的模块会从 package、源码、依赖、Composition、Manifest、schema、migration 和模块文档中物理排除，而不是只隐藏菜单或关闭 Feature。模块依赖会自动补齐；未知 模块和不闭合组合会在写入前拒绝。

常用选项

完整帮助：

npx create-windy@latest --help

生成后

cd my-dashboard
bun run dev

create-windy 会生成仅供本机使用、被 Git 忽略且权限为 0600 的 .env，其中数据库 与管理员开发密码均为随机值。全新数据库的初始平台账号固定为 admin，初始密码查看 .env 中的 WINDY_BOOTSTRAP_ADMIN_PASSWORD；创建器只提示密码位置，不会把随机密码 直接打印在终端。首次登录必须修改密码，新密码需要 12-128 个字符，且不能与当前密码 相同。

bun run dev 会复用已有 Docker 镜像，等待 PostgreSQL、执行 migration，再启动支持 热更新的 Server 与 Web；首次缺少镜像时才会构建。依赖、Dockerfile 或 bun.lock 变化后运行 bun run dev:build。首次运行前需安装并启动 Docker 与 Docker Compose。 dev:build 会先执行 create-windy sync-docker，根据 apps/web 当前直接与传递 workspace 依赖重建 Dockerfile 的 deps/build COPY 锚点段；新增业务 package 后不再 需要手工补 COPY packages/<name>。 Windows 10/11 可在原生 PowerShell 中配合 Docker Desktop 直接运行上述两个命令， 不需要 WSL；sync-docker 会使用 Windows 原生原子替换与 no-replace move 完成同一套 并发保护和事务清理。Windows 仅作为本地开发宿主，生产交付仍是 Linux amd64 容器。 环境变量只负责初始化全新数据库，数据库已有管理员后，重启服务不会重新覆盖其密码。

只调试单个应用时可分别使用 bun run dev:web 和 bun run dev:server。dev:web 不会 隐式启动后端；dev:server 也不会自动启动 PostgreSQL 或执行 migration。

生成项目会固定安装与创建器同版本的生命周期 CLI，并提供：

bun run windy doctor
bun run windy sync-docker
bun run windy update --check
bun run windy update --dry-run
bun run windy update

0.6.6 是 Starter 更新的最低支持基线。更新器不检查 Git 工作区是否干净：只规划 目标版本实际变更的受管文件，从 source Project Lock 指向的精确 npm artifact 重建 Base，并以 Base/Ours/Theirs 合并共享脚手架。未触及的业务修改不会进入更新判断； package.json 使用字段级合并；已发布 migration 只允许追加；冲突发生时不写项目， 验证失败则从 .windy/backups/ 自动回滚。项目锁定的 CLI 检测到新版后，会委托给 目标版本生成完整更新计划。

受管清单使用 schema v4：hash 冻结下游实际正文，artifactHash 在两者不同时记录 公开模板基线；无正文的 missing tombstone 记住客户删除的 project-owned 路径。 低于 0.6.6 的 Project Lock、旧清单 schema、损坏的 artifact lineage 或 recipe 缺口都会在写文件前 fail closed，不提供旧状态的自动迁移路径。

生成后的整个 apps/web/src 与整个 apps/server/src/app 都是 project-owned。普通 更新不会重写 Admin 布局、页面、组件库、Router、Host 或 Server 模块装配；失去 Manifest/Host 协议时只报告兼容错误。

本地 Web 默认使用 8746；如果该端口属于其它服务，会自动尝试 8747、8748 等端口。 如果检测到同一个项目已启动，则直接复用现有地址。

默认创建流程会在依赖安装和 Git 初始化后启用 Husky。使用 --skip-install 时，后续 执行 bun install 会完成启用；使用 --no-git 后自行初始化 Git，则再运行一次 bun run prepare。

安全与分发边界

客户项目只来自 npm 包内的已清理模板快照，不需要访问 Windy 私有源仓库。供应方 License Authority、内部签名服务、Secret、开发凭据、本机绝对路径和运行状态不会进入 生成物。创建失败默认事务化清理；--keep-on-error 是显式诊断例外。

create-windy 与它分发的 Windy Starter 基座使用 Apache-2.0；完整正文随包发布， 生成项目会保留在 .windy/licenses/WINDY-APACHE-2.0.txt。项目所有者新增的业务代码 法律许可仍由创建时的 --license 独立决定，默认 UNLICENSED，不会因为使用了 Apache-2.0 基座而自动开源客户业务代码。

模块生命周期

新生成项目的数据库镜像为 pgvector/pgvector:pg18，使用 PG18 默认数据目录和新的 postgres18-data 卷。镜像预装 pgvector，平台默认不启用 vector 扩展，也不创建 业务向量表；需要向量检索时由业务模块的迁移声明。PG18 正式发布证据需在新候选上取得， 历史 PG17 证据不变。

创建期模块物理组合已达到 H2：默认、纯核心、全模块和无 Oxc 组合持续执行真实安装、 类型检查、测试和构建，模块组合还在 PostgreSQL 18 上验证首次/重复迁移与 Server 启动。部署期使用同一个项目内 CLI：

bun run windy module list
bun run windy module disable work-order --dry-run
bun run windy module disable work-order
bun run windy module enable work-order

windy.modules.json 是 project-owned 装配选择，记录无版本 package 入口、启用状态、 顺序、Admin 可见性与模块配置；实际版本只来自 package.json 和 bun.lock。 enable/disable 只通过 CAS 事务修改该文件，不卸载 package，也不改 Admin、Router、 layout 或 Host。system.settings、system.storage 与 system.data-governance 有跨模块 Feature/Route 贡献，不能安全 runtime disable， 部署后排除必须人工物理迁移。当前所有内置模块都需要 project-owned Composition；对实际集合变化执行 add/update/remove 会在写项目之前 fail closed。任意 npm package 名称安装也尚未交付。 正式变更在交互终端展示计划后确认；CI、Agent 或其它非 TTY 环境必须显式传入 --yes，--dry-run 始终只预览。

命令不检查 Git 工作区是否干净；装配变更使用 CAS 事务，未触及的业务改动完全保留。 CLI 与项目 Windy 版本必须兼容，旧项目先执行 bun run windy update。旧的源码再生成式 work-order 回归不能作为新模块协议的 H3 证据；只有 self-contained package 在不改 客户源码的前提下完成安装、更新、数据处置卸载和重装回归，才允许恢复 H3 声明。