Macro 本地全栈部署教程DockerLocalStack 一键启动 42 个服务【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macroMacro 是一款集成邮件、聊天、文档、任务、AI Agent 与 CRM 的团队统一工作区。本教程带你用 Docker LocalStack 在本地一键启动 Macro 的完整后端栈——42 个可部署服务、6 大基础设施全部容器化无需任何云平台密钥几分钟内跑起真实可用的全栈环境。Macro 采用SolidJS Rust构建前端一个客户端后端 42 个服务、167 个 Rust 库协作运行。官方为本地开发提供了完整的 Compose 编排docker/docker-compose.yml和 LocalStack 模拟脚本tooling/just/local_stack.just让你不依赖 Doppler、不用真实 AWS 账号也能完整体验认证、文档、邮件、搜索等核心功能。 本教程基于官方本地运行指南 docs/RUNNING_LOCALLY.md所有命令均可在仓库根目录直接执行。一、部署前准备环境与依赖清单1. 唯一宿主依赖安装 NixMacro 的 Nix 开发 Shell 会一次性提供just、Cargo、Rust 工具链、Bun、wasm-pack 等全部工具你不需要单独安装任何依赖git clone https://gitcode.com/GitHub_Trending/macro3/macro cd macro nix develop如果nix develop报错启用实验特性后再运行一次nix develop --extra-experimental-features nix-command --extra-experimental-features flakes Linux 上 Nix Shell 还自带 Docker CLI、守护进程与 ComposemacOS 需额外安装一个 Docker 运行时Docker Desktop、OrbStack 或 Colima。2. 端口体检just doctor-local默认实例会占用一批固定端口Postgres 5432、Redis 6379、Kafka 9092、OpenSearch 9200、LocalStack 4566、前端 3000 等。启动前先做体检just doctor-local它会检查 Docker 守护进程、工具链和端口占用发现问题会直接给出修复建议。macOS 上 8080/8090 常被系统服务抢占体检命令能提前暴露这类冲突。二、一键启动just run_local 全栈拉起1. 执行启动命令just run_local --no-doppler这一条命令完成了四件事用cargo zigbuild在宿主机编译全部 Rust 后端服务启动本地基础设施Postgrespgvector/pg18、Redis Stack、KafkaKRaft 单节点、OpenSearch、LocalStack、FusionAuth启动后端服务与本地代理启动 Vite 前端打印前端 URL 与关键服务地址。没有 Doppler 权限时加--no-doppler即可——栈会使用代码内置的本地配置、模拟 AWS 凭据与固定测试密钥。第三方集成Google、GitHub、Stripe以桩值启动本地注册登录、文档、邮件、搜索功能均完整可用。2. 首次登录在 Mailpit 里收验证码本地栈不预建账号采用密码less 登录注册时填任意邮箱FusionAuth 发送的一次性验证码邮件会落到本地Mailpithttp://localhost:8025而不是真实收件箱。打开 Mailpit 复制验证码即可完成登录全程离线闭环。3. 热键与停止运行期间按r重新构建变更的 Rust 服务并热加载务必按q停止栈它会同时停止并清理容器避免下次启动时残留脏状态。三、架构速览6 大基础设施 LocalStack 模拟 AWS核心编排定义在 docker/docker-compose-databases.yml各业务服务在 docker/docker-compose.yml 中声明全部带健康检查并按依赖顺序启动。组件本地端口角色Postgres (pgvector/pg18)5432主数据库向量检索Redis Stack6379缓存与会话Kafka (KRaft)9092事件流OpenSearch9200全文搜索索引LocalStack v44566模拟 S3 / SQS / DynamoDBFusionAuth9011认证与邮件验证码LocalStack本地迷你 AWStooling/just/local_stack.just 中的setup_localstack配方会自动启动 LocalStack 容器端口 4566并挂入databases网络创建 26 条 SQS 队列邮件回填、通知、上传终结器等创建 3 张 DynamoDB 表批量上传、连接网关、静态文件元数据创建 6 个 S3 桶并配置 CORS把doc-storage桶的 ObjectCreated 事件打通到本地上传终结器 Worker。也就是说生产环境走 AWS 的全部异步管道S3 事件 → SQS → Worker在本地被 LocalStack 1:1 复刻——这正是一键启动能够覆盖邮件附件、文档上传等完整链路的关键。四、种子数据给空栈注入一个真实团队裸栈没有任何内容。官方 Seed CLI 可以一键注入包含用户、团队、频道、文档、任务、邮件与消息的完整演示世界含真实权限模型just seed-scenario apply --file seed/scenarios/team-perms.json场景文件位于 tooling/seed_cli/seed/scenarios/team-perms.json。apply会为每个人物创建 FusionAuth 账号并打印独立登录链接如http://alice.localhost:3000/app/login?emailaliceseed.macro.local。不同人物主机名各自持有 Cookie你可以在一个栈上并排切换多个角色验证权限。配套命令status— 查看已注入内容并重新打印登录链接reset— 清理该场景的数据行与账号matrix— 逐条核对用户 × 实体的预期访问级别。五、日常运维命令速查表命令作用just run_local --no-doppler启动完整本地栈最常用just doctor-local检查 Docker、工具链、端口just status_local只读查看端点与容器状态just stop_local停止实例但保留数据卷just reset_local删库重建并重新迁移just destroy_local彻底删除容器、卷与网络just stack up无头模式启动前端静态化适合 CI/Agent需要并行跑多个栈时用--instance agent-a创建命名实例每个实例拥有独立的 Compose 项目、卷、网络与端口窗口端口被占用时可用--port-base 31000整体平移端口。六、常见问题快速排查① 页面能打开但登录/API 返回 HTML 或报错大概率是端口被抢占macOS 的 WebDriver 占 8080、其他项目占 8090。运行just doctor-local找出被占用端口然后换端口窗口启动just run_local --no-doppler --instance test --port-base 31000② 改动了同步/协作相关服务却不生效sync_service、lexical_service、websocket_service三个服务使用 Docker 构建镜像默认不随run_local重建。加--build-aux-services强制重建再按r热加载。③ 第三方集成功能不可用Google/GitHub/Stripe 等集成默认使用桩值。把真实密钥写入local.env再执行just run_local --no-doppler --env-file ./local.env即可按需开启文件中的键会覆盖内置默认值。④ 数据库状态乱了直接just reset_local删库重建并跑完 338 个迁移文件见 crates/macro_db_client/migrations/无需手动操作 Postgres。七、总结通过本教程你已经掌握了 Macro 本地全栈部署的完整路径Nix 开发 Shell 准备环境 →just doctor-local体检 →just run_local --no-doppler一键启动 42 个服务 → Mailpit 完成登录 → Seed CLI 注入演示数据。得益于 Docker Compose 编排与 LocalStack 对 AWS 的 1:1 模拟整个本地栈与生产架构同构你在本地验证的每一条链路邮件、搜索、上传、Agent都能在真实环境中复现。项目源码遵循 AGPLv3 开源协议更多开发约定参见 docs/STYLE_GUIDE.md 与 CONTRIBUTING.md。【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Macro 本地全栈部署教程：Docker+LocalStack 一键启动 42 个服务
Macro 本地全栈部署教程DockerLocalStack 一键启动 42 个服务【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macroMacro 是一款集成邮件、聊天、文档、任务、AI Agent 与 CRM 的团队统一工作区。本教程带你用 Docker LocalStack 在本地一键启动 Macro 的完整后端栈——42 个可部署服务、6 大基础设施全部容器化无需任何云平台密钥几分钟内跑起真实可用的全栈环境。Macro 采用SolidJS Rust构建前端一个客户端后端 42 个服务、167 个 Rust 库协作运行。官方为本地开发提供了完整的 Compose 编排docker/docker-compose.yml和 LocalStack 模拟脚本tooling/just/local_stack.just让你不依赖 Doppler、不用真实 AWS 账号也能完整体验认证、文档、邮件、搜索等核心功能。 本教程基于官方本地运行指南 docs/RUNNING_LOCALLY.md所有命令均可在仓库根目录直接执行。一、部署前准备环境与依赖清单1. 唯一宿主依赖安装 NixMacro 的 Nix 开发 Shell 会一次性提供just、Cargo、Rust 工具链、Bun、wasm-pack 等全部工具你不需要单独安装任何依赖git clone https://gitcode.com/GitHub_Trending/macro3/macro cd macro nix develop如果nix develop报错启用实验特性后再运行一次nix develop --extra-experimental-features nix-command --extra-experimental-features flakes Linux 上 Nix Shell 还自带 Docker CLI、守护进程与 ComposemacOS 需额外安装一个 Docker 运行时Docker Desktop、OrbStack 或 Colima。2. 端口体检just doctor-local默认实例会占用一批固定端口Postgres 5432、Redis 6379、Kafka 9092、OpenSearch 9200、LocalStack 4566、前端 3000 等。启动前先做体检just doctor-local它会检查 Docker 守护进程、工具链和端口占用发现问题会直接给出修复建议。macOS 上 8080/8090 常被系统服务抢占体检命令能提前暴露这类冲突。二、一键启动just run_local 全栈拉起1. 执行启动命令just run_local --no-doppler这一条命令完成了四件事用cargo zigbuild在宿主机编译全部 Rust 后端服务启动本地基础设施Postgrespgvector/pg18、Redis Stack、KafkaKRaft 单节点、OpenSearch、LocalStack、FusionAuth启动后端服务与本地代理启动 Vite 前端打印前端 URL 与关键服务地址。没有 Doppler 权限时加--no-doppler即可——栈会使用代码内置的本地配置、模拟 AWS 凭据与固定测试密钥。第三方集成Google、GitHub、Stripe以桩值启动本地注册登录、文档、邮件、搜索功能均完整可用。2. 首次登录在 Mailpit 里收验证码本地栈不预建账号采用密码less 登录注册时填任意邮箱FusionAuth 发送的一次性验证码邮件会落到本地Mailpithttp://localhost:8025而不是真实收件箱。打开 Mailpit 复制验证码即可完成登录全程离线闭环。3. 热键与停止运行期间按r重新构建变更的 Rust 服务并热加载务必按q停止栈它会同时停止并清理容器避免下次启动时残留脏状态。三、架构速览6 大基础设施 LocalStack 模拟 AWS核心编排定义在 docker/docker-compose-databases.yml各业务服务在 docker/docker-compose.yml 中声明全部带健康检查并按依赖顺序启动。组件本地端口角色Postgres (pgvector/pg18)5432主数据库向量检索Redis Stack6379缓存与会话Kafka (KRaft)9092事件流OpenSearch9200全文搜索索引LocalStack v44566模拟 S3 / SQS / DynamoDBFusionAuth9011认证与邮件验证码LocalStack本地迷你 AWStooling/just/local_stack.just 中的setup_localstack配方会自动启动 LocalStack 容器端口 4566并挂入databases网络创建 26 条 SQS 队列邮件回填、通知、上传终结器等创建 3 张 DynamoDB 表批量上传、连接网关、静态文件元数据创建 6 个 S3 桶并配置 CORS把doc-storage桶的 ObjectCreated 事件打通到本地上传终结器 Worker。也就是说生产环境走 AWS 的全部异步管道S3 事件 → SQS → Worker在本地被 LocalStack 1:1 复刻——这正是一键启动能够覆盖邮件附件、文档上传等完整链路的关键。四、种子数据给空栈注入一个真实团队裸栈没有任何内容。官方 Seed CLI 可以一键注入包含用户、团队、频道、文档、任务、邮件与消息的完整演示世界含真实权限模型just seed-scenario apply --file seed/scenarios/team-perms.json场景文件位于 tooling/seed_cli/seed/scenarios/team-perms.json。apply会为每个人物创建 FusionAuth 账号并打印独立登录链接如http://alice.localhost:3000/app/login?emailaliceseed.macro.local。不同人物主机名各自持有 Cookie你可以在一个栈上并排切换多个角色验证权限。配套命令status— 查看已注入内容并重新打印登录链接reset— 清理该场景的数据行与账号matrix— 逐条核对用户 × 实体的预期访问级别。五、日常运维命令速查表命令作用just run_local --no-doppler启动完整本地栈最常用just doctor-local检查 Docker、工具链、端口just status_local只读查看端点与容器状态just stop_local停止实例但保留数据卷just reset_local删库重建并重新迁移just destroy_local彻底删除容器、卷与网络just stack up无头模式启动前端静态化适合 CI/Agent需要并行跑多个栈时用--instance agent-a创建命名实例每个实例拥有独立的 Compose 项目、卷、网络与端口窗口端口被占用时可用--port-base 31000整体平移端口。六、常见问题快速排查① 页面能打开但登录/API 返回 HTML 或报错大概率是端口被抢占macOS 的 WebDriver 占 8080、其他项目占 8090。运行just doctor-local找出被占用端口然后换端口窗口启动just run_local --no-doppler --instance test --port-base 31000② 改动了同步/协作相关服务却不生效sync_service、lexical_service、websocket_service三个服务使用 Docker 构建镜像默认不随run_local重建。加--build-aux-services强制重建再按r热加载。③ 第三方集成功能不可用Google/GitHub/Stripe 等集成默认使用桩值。把真实密钥写入local.env再执行just run_local --no-doppler --env-file ./local.env即可按需开启文件中的键会覆盖内置默认值。④ 数据库状态乱了直接just reset_local删库重建并跑完 338 个迁移文件见 crates/macro_db_client/migrations/无需手动操作 Postgres。七、总结通过本教程你已经掌握了 Macro 本地全栈部署的完整路径Nix 开发 Shell 准备环境 →just doctor-local体检 →just run_local --no-doppler一键启动 42 个服务 → Mailpit 完成登录 → Seed CLI 注入演示数据。得益于 Docker Compose 编排与 LocalStack 对 AWS 的 1:1 模拟整个本地栈与生产架构同构你在本地验证的每一条链路邮件、搜索、上传、Agent都能在真实环境中复现。项目源码遵循 AGPLv3 开源协议更多开发约定参见 docs/STYLE_GUIDE.md 与 CONTRIBUTING.md。【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
