wslc-compose

wslc-compose 是面向 Windows WSL Containers (wslc.exe) 的严格 Compose 子集前端。它使用 compose-go/v2 完成 Compose 文件发现、插值、合并、profiles 过滤和标准化，再将可可靠表达的配置转换为 WSLC 参数数组。它不依赖 Docker Desktop、Docker daemon、Python、Node.js 或后台守护进程。

当前版本：0.1.0-dev。WSLC 仍在快速演进，所有运行时参数都以本机 wslc ... --help 探测结果为准。

构建

要求 Go 1.24 或更高版本。本仓库开发验证使用 Conda minidev 环境中的 Go。

conda activate minidev
go test ./...
go vet ./...
.\scripts\build.ps1

产物为单个静态链接文件：

dist\wslc-compose.exe

仓库的 GitHub Actions 会在每次 push、pull request 以及手动触发时执行测试、vet、格式检查，并构建 Windows amd64/arm64。成功后可在对应 Actions 运行页面的 Artifacts 区域下载两个 EXE 和 checksums.txt；普通 CI 产物保留 30 天，它们不是永久 GitHub Release。

推送 SemVer 标签会创建永久 GitHub Release：

git tag v0.1.0
git push origin v0.1.0

Release 工作流会重新执行测试、vet 和格式检查，将标签版本、提交 SHA 和构建时间注入二进制，然后发布 wslc-compose_windows_amd64.exe、wslc-compose_windows_arm64.exe 和 checksums.txt。带后缀的标签 （例如 v0.2.0-rc.1）会自动创建为 prerelease。重复运行同一标签的工作流会覆盖已有 Release 资源。

快速开始

wslc-compose doctor --refresh
wslc-compose -f .\examples\compose.yaml config
wslc-compose -f .\examples\compose.yaml plan
wslc-compose -f .\examples\compose.yaml up -d
wslc-compose -f .\examples\compose.yaml ps
wslc-compose -f .\examples\compose.yaml logs -f web
wslc-compose -f .\examples\compose.yaml exec web cat /etc/os-release
wslc-compose -f .\examples\compose.yaml down

默认状态目录是 %USERPROFILE%\.wslc-compose。可用 WSLC_COMPOSE_HOME 或 --state-dir 覆盖。状态只保存项目 归属、资源名、不可逆配置摘要和运行时 ID，不保存环境变量值、.env 内容或凭据。

命令

• version [--json]
• doctor [--refresh] [--json]
• config [--json] [--services] [--show-secrets]
• plan [--json]
• up [-d] [--build] [--force-recreate] [--no-recreate] [--remove-orphans] [SERVICE...]
• down [--volumes] [--timeout 10s]
• ps [--all] [--json]
• logs [-f] [--tail N] [SERVICE...]
• exec [-T] SERVICE COMMAND [ARG...]

全局支持重复 -f/--file、-p/--project-name、--project-directory、重复 --env-file、重复 --profile、--compatibility strict|permissive、--state-dir、--wslc-path 和 --json。

Compose 兼容范围

支持或按本机能力支持：

• 顶层 name、services 和基础命名卷；
• image、本地 build.context、build.dockerfile/args/no_cache/pull/target；
• command、单 token entrypoint、environment、env_file；
• TCP ports（UDP 在运行探针确认前保持未知并阻止执行）；
• bind 和 named volumes；
• working_dir、hostname、domainname、user、privileged、gpus；
• depends_on 的短语法和 service_started；
• profiles；
• x-* 扩展字段安全忽略。

默认阻止：

• 自定义网络、IPAM 和网络 aliases；
• configs、secrets；
• restart、healthcheck、service_healthy；
• deploy、replicas/scale；
• devices、cap_add/cap_drop、sysctls、ulimits；
• IPC/PID namespace 映射；
• 任何本机帮助未确认的 WSLC 参数。

labels、expose、显式 container_name 等文档标记的安全降级会产生 warning；严格模式下 warning 也会阻止 up，可在审阅计划后显式使用 --compatibility permissive。网络、挂载、端口、命令和环境等语义字段不会在 permissive 模式下静默忽略。

安全与恢复

• 外部命令仅使用 exec.CommandContext(path, args...)，不通过 PowerShell/CMD 拼接执行用户输入；
• plan 的 PowerShell 命令仅供展示，执行器从不使用展示字符串；
• 环境变量和 build args 在诊断、计划和默认 config 输出中脱敏；
• 每个项目使用独占锁；状态先写同目录临时文件、同步并校验，再保留 .bak 后替换；
• up 失败默认逆序回滚本次新建的容器，不接管名称冲突的未知容器；
• down 只操作状态中明确记录为本工具创建的资源，默认保留命名卷和 external 卷。

已知限制

• 每个服务只管理一个容器；
• v0.1 使用 WSLC CLI，不直接绑定预览中的原生 Container API；
• ps 的 JSON 解析对已知 WSLC JSON 字段做兼容处理，新版 schema 变化可能需要更新；
• 多服务 logs -f 当前顺序执行，不做并发日志复用；
• 状态替换在 Windows 上保证不会暴露半个 JSON 并保留备份，但不是跨文件事务；
• 本仓库开发机探测到 WSLC 2.9.4.0；真实镜像拉取和容器生命周期集成测试需要显式运行 scripts\integration-test.ps1 -RunLive，普通单元测试不会修改本机容器。

许可证

本项目使用 Apache-2.0。依赖许可证见 THIRD_PARTY_NOTICES.md。