关于 polar-local-environment
Local Environment Skill 指导开发者通过 `dev docker` CLI 管理 Polar 本地开发环境。它说明共享基础设施与按 worktree 隔离的应用栈，并提供实例端口、日志和故障排查指引。
主要功能
- 01启动、停止和重启本地环境
- 02查看实例端口与服务状态
- 03管理并行 worktree 实例
- 04查看日志、进入容器并执行命令
- 05区分应用栈与共享基础设施
适用场景
- 01启动或排查本地服务
- 02并行运行多个隔离的 worktree 环境
- 03查找服务实际端口和访问地址
- 04清理单个实例或共享数据
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/polar-local-environment确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
rules/manage-instances.mdpayment-testing.mdservice-architecture.mdshell-and-workflows.mdstart-environment.mdstop-environment.mdtroubleshooting.mdview-logs.md详细介绍
本地环境技能
通过 dev docker CLI 管理 Polar 本地开发环境。可用于启动、停止、调试本地服务栈，或了解其运行情况。
两部分模型
dev docker 有意将服务栈拆分，以便多个工作树共用一套资源占用较大的基础设施：
- 共享基础设施 — 每台机器一份，Docker 项目为
polar-shared： postgres、redis、minio、tinybird，以及可选的 prometheus/grafana。Postgres 和 redis 不发布主机端口；MinIO 开放 9000/9001，供浏览器上传使用。对于未开放主机端口的服务，请使用dev docker exec <service> ...。 - 每个实例的应用服务栈 — 每个工作树一份，项目为
polar-app-<N>：api、 worker、web。只有 api 和 web 发布主机端口，且每个实例的端口偏移不同，以免工作树之间发生冲突。
了解这一点有助于避免最常见的困惑：数据库没有对应的 localhost:5432（它位于共享服务栈中，应通过
dev docker exec db ... 访问）。MinIO 确实开放 9000/9001 端口，供浏览器上传和访问控制台。
实例自动检测
dev docker 会自动检测当前工作树的实例，因此很少需要使用 -i。优先级如下：
- 在
dev/docker/.env.docker中固定的POLAR_DOCKER_INSTANCE（dev docker set-instance N） - 跨工作树注册表（
~/.config/polar/docker-instances.json） - 否则，使用最小的空闲编号，再进行注册
运行 dev docker ports 可查看解析出的实例及其 URL（工具可添加 --json）。
若要将此工作树接入 Claude Code 的预览，请运行
dev docker launch-json。该命令会写入包含正确端口的每实例 .claude/launch.json（此文件已被 gitignore 忽略，因此在执行 set-instance 后需重新生成）。
适用场景
- 启动 / 停止 / 重启本地环境
- 查看日志，或调试无法启动的服务
- 并行运行多个相互隔离的工作树实例
- 了解服务架构或查找服务的实际端口
- 排查容器或首次启动时的错误
快速参考
| 任务 | 命令 |
|---|---|
| 在后台启动完整服务栈 | dev docker up -d |
| 启动并等待服务就绪 | dev docker up -d --wait |
| 在前台启动（持续输出日志） | dev docker up --no-detach |
| 使用最新基础镜像重新构建 | dev docker up -b --pull -d |
| 显示此实例的端口 / URL | dev docker ports（工具可使用 --json） |
| 写入 Claude Code 预览配置 | dev docker launch-json |
| 停止应用服务栈 | dev docker down |
| 停止应用服务栈 及 共享基础设施 | dev docker down --all |
| 持续查看日志 | dev docker logs -f [service] |
| 输出日志后退出 | dev docker logs --no-follow [service] |
| 查看状态 | dev docker ps |
| 重启服务 | dev docker restart <service> |
| 进入服务的 Shell | dev docker shell <service> |
| 在服务中运行一次性命令 | dev docker exec <service> <cmd> |
| 重置此实例 | dev docker cleanup -f |
| 清除所有共享数据 | dev docker cleanup --all -f |
| 列出所有实例 | dev docker list |
| 启用监控 | dev docker up --monitoring -d |
服务
| 服务 | 项目 | 主机端口（实例 0 / N） | 备注 |
|---|---|---|---|
| api | polar-app-<N> | 8000 / 8100+N | FastAPI；/healthz 健康检查 |
| web | polar-app-<N> | 3000 / 3100+N | Next.js；启用健康检查 |
| worker | polar-app-<N> | 无 | 后台任务 |
| db | polar-shared | 无（exec） | PostgreSQL；数据库 polar_dev_<N> |
| redis | polar-shared | 无（exec） | Redis 数据库索引 = N |
| minio | polar-shared | 9000、9001 | S3；存储桶 polar-s3-<N>；控制台位于 9001 |
| tinybird | polar-shared | 无（exec） | 分析 |
| prometheus / grafana | polar-shared | 无（exec） | 仅在使用 --monitoring 时启用 |
运行 dev docker ports 可查找当前工作树对应的确切主机端口。
实例端口映射
只有 api 和 web 会映射到主机端口：实例 1–99 使用 端口 = 基数 + 实例（api 的基数为 8100，web 的基数为 3100）。实例 0 使用旧版端口 8000 / 3000。
| 实例 | API | Web |
|---|---|---|
| 0 | 8000 | 3000 |
| 1 | 8101 | 3101 |
| 2 | 8102 | 3102 |
| 5 | 8105 | 3105 |
其他服务都是按实例隔离，但不映射到主机端口：数据库 polar_dev_<N>、Redis DB 索引 <N>、存储桶 polar-s3-<N> / polar-s3-public-<N>。通过 dev docker exec <service> 或 docker exec polar-shared-<service>-1 访问它们。
规则索引
| 规则 | 类别 | 描述 |
|---|---|---|
| service-architecture | 参考 | 服务详情、端口、健康检查 |
| start-environment | 操作 | 启动堆栈（标志、--wait、--pull） |
| stop-environment | 操作 | 停止和清理（应用与共享服务） |
| manage-instances | 操作 | 并行 worktree 实例 |
| view-logs | 调试 | 查看服务日志 |
| shell-and-workflows | 操作 | Shell 访问和常见开发工作流 |
| troubleshooting | 调试 | 常见错误及修复方法 |
| payment-testing | 操作 | 登录码、Stripe webhook、后台管理 |