01先确认源码访问权限
源码仓库保持私有。下方链接供已获授权的协作者使用；未登录或没有权限时可能返回 404。这个网站不提供公开源码下载，也不承诺所有访客都可以 clone。
如果已有权限，可 clone 仓库或打开现有 checkout，在仓库根目录运行后续命令。如果还没有权限，可先学习公开课程和原始资料；获得所有者授权后再做本地复现。
02准备运行环境
- 在 macOS 或 Linux 使用 Bash。Windows 应使用与 Docker 集成的 WSL2 Linux shell；原生 PowerShell 不是启动器的运行环境。
- 安装 Docker、Compose v2、Python 3 和 curl，并确保 Docker daemon 可访问。macOS 可以选用 Colima，但它不是所有平台的必需依赖。
- 建议为 Docker 预留至少 10 GiB 内存，准备约 30 GiB 可用磁盘以容纳镜像和数据。这是容量规划基线，不是经过验证的最低配置或性能承诺。
- 首次构建会下载容器镜像和连接器 JAR，需要能访问相应仓库。请在自己的机器上确认镜像可用性和 CPU 架构支持。
- 启动器适配这些平台约定；本版不声称已在每个平台完成新的全栈集成运行。
03初始化、诊断、启动
初始化会创建本地配置，不覆盖已有文件。检查示例及端口选择，再运行 doctor，先解决错误再启动全栈。
Open 启动本地服务并输出控制台地址，请在同一台机器上访问。学习服务应保持 loopback 绑定；公开阅读站不会连接它们。
先启动所选的 Docker 环境。macOS 如选用 Colima，可用 ./stream-lab open --colima 显式启动；常规 close 不会停止共享 Docker 虚拟机。
./stream-lab init
./stream-lab doctor
./stream-lab open
./stream-lab status
./stream-lab smoke04清晰的日常操作循环
| 任务 | 命令 | 含义 |
|---|---|---|
| 查看状态 | ./stream-lab status | 显示本地项目容器状态 |
| 检查数据链路 | ./stream-lab smoke | 执行服务、作业和查询检查；失败时查看具体断言 |
| 查看日志 | ./stream-lab logs | 跟踪近期服务日志；Ctrl-C 退出跟踪 |
| 运行有界计算 | ./stream-lab batch | 执行小时聚合和行数对账 |
| 使用高级 SQL | make sql | 进入本地 Flink SQL Client 自由查询 |
| 停止实验 | ./stream-lab close | 停止本项目并保留 named volumes |
05从第一个失败边界开始排查
| 现象 | 下一步检查 |
|---|---|
| 无法访问 Docker | 启动所选 Docker 环境，再运行 doctor。 |
| 端口已被占用 | 检查本地配置和现有监听，选择空闲端口后重试。 |
| 镜像或连接器下载失败 | 查看最早的构建错误、仓库访问和镜像架构兼容性。 |
| 容器运行但没有数据 | 先查 MySQL 与 mock-producer，再查 CDC 作业和 Join 作业。 |
| 湖表查询超时 | 检查 SQL Gateway、Flink 空闲 slot、tiering 和 sink 提交错误。 |
| 小时汇总没有更新 | 查 batch-runner 日志及作业完成情况，再查 Kafka 消费。 |
| 修改 SQL 后出现重复作业 | 重新提交前有意识地取消旧作业，不要反复启动同名持续作业。 |
06理解停止与保留的语义
停止实验会保留 named volumes，但这不等于备份，不会自动清理全部旧湖文件，也不代表具备持久化高可用恢复方案。除非明确要清空实验数据，否则不要使用删除数据卷的命令。
代码在多个源端、日志、状态和服务层设置了七天保留；这些设置语义不同，清理时机也不同。当前没有实现定期 Iceberg 快照过期和完整湖文件清理流程。
本地组件采用仅适合学习的认证安排。不要通过隧道或端口转发把 Compose 栈发布成公网服务。本地配置与原始日志不会被导出到阅读站。