IntentKit 本地部署指南基于 Docker Compose 快速预览你的云端 Agent 集群【免费下载链接】intentkitIntentKit is an open-source, self-hosted cloud agent cluster that manages a collaborative team of AI agents for you.项目地址: https://gitcode.com/GitHub_Trending/int/intentkit本指南围绕 docs/content/en/deployment/local.md 展开完整讲解如何在本地开发机上快速拉起 IntentKit 的整套技术栈并完成验证。IntentKit 是一个开源的、自托管的云原生 Agent 集群详见 README.md本指南面向希望先跑起来再评估的开发者读完本文你将掌握从克隆代码、配置.env、启动 Postgres/Redis/RustFS 及 API、后台任务与前端等全部服务到健康检查、日志排查和干净卸载的完整本地预览流程并理解这些配置项在源码中的真实加载逻辑。本地预览模式定位在 部署文档总览 中IntentKit 官方提供三种部署形态Local本指南用于在自有开发机上快速预览与评估强调零配置、开箱即用Docker Compose用于远程服务器部署参见 docker-compose.mdDocker Swarm面向生产级的多节点部署。三种方式都运行同一套组件API 服务器、后台工作进程以及支撑服务 Postgres、Redis 与 RustFS。本地模式与服务器模式的核心差异在于本地模式走的是仓库根目录下的 docker-compose.yml通过源码构建 热重载而服务器模式使用 deployment/docker-compose.yml预构建镜像 Caddy 反向代理 HTTPS。因此本地预览无需域名、无需证书、无需开放公网端口。前置条件准备本地 Docker 运行时macOS 上的最小安装官方文档推荐的 macOS 组合是Colima Docker Compose Docker Buildx其中 Colima 负责提供 Linux 虚拟机运行时docker-compose 与 docker-buildx 则作为 Docker CLI 的插件工作brew update brew install colima docker-compose docker-buildx由于 Homebrew 安装的插件不在 Docker CLI 默认的插件搜索路径内需要在~/.docker/config.json中显式声明插件目录{ cliPluginsExtraDirs: [ /opt/homebrew/lib/docker/cli-plugins ] }然后启动 Docker 运行时colima start其他操作系统请按照 Docker 官方文档安装 Docker 与 Docker Compose。Linux 用户一般只需安装docker-ce、docker-compose-plugin即可Windows 建议使用 WSL2 后端。版本与功能要求从根目录 docker-compose.yml 使用的指令如condition: service_healthy依赖控制、build.args、env_file可以推断本地预览需要Docker Compose v2以上版本它支持健康检查依赖与构建参数传递等现代特性。获取代码克隆仓库并进入目录git clone https://github.com/crestalnetwork/intentkit.git cd intentkit如果仓库已存在本地副本直接进入目录即可无需重复克隆。初始化环境配置仓库根目录提供了完整的环境变量模板将其复制为.envcp .env.example .env随后编辑.env至少配置一个 LLM Provider 的 API Key例如OPENAI_API_KEY。这是整个集群能够运转的前提——Agent 的所有对话、自主执行与内容生成都依赖 LLM 推理。本地模式可以留空的配置项官方文档明确说明本地预览时以下配置留空即可模板中的默认值已经为本地开发调校好APP_DOMAIN——应用域名本地模式不需要域名TLS_EMAIL——Lets Encrypt 证书注册邮箱仅服务器模式启用 HTTPS 时需要认证相关配置BASIC_AUTH_USER/BASIC_AUTH_PASSWORD——Web 界面基础认证留空即禁用。从 .env.example 的注释可以看到模板第一行就声明了ENVlocal、DEBUGtrueAPP_DOMAIN与TLS_EMAIL被标注为部署时需要、本地开发留空。理解 .env 中的关键配置族虽然本地预览只需填一个 LLM Key但了解模板中的配置分组有助于后续评估与调试配置族关键变量说明LLM ProvidersOPENROUTER_API_KEY、OPENAI_API_KEY、DEEPSEEK_API_KEY、XAI_API_KEY、GOOGLE_API_KEY、MINIMAX_PLAN_API_KEY等至少配置一个还支持OPENAI_COMPATIBLE_*与ANTHROPIC_COMPATIBLE_*接入任意兼容端点数据库DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_NAME、DB_AUTO_MIGRATE使用 compose 内建的 Postgres 时全部留空由 docker-compose.yml 注入默认值RedisREDIS_HOST、REDIS_PORT、REDIS_DB同样由 compose 注入对象存储AWS_S3_BUCKET、AWS_S3_ENDPOINT_URL、AWS_S3_REGION_NAME等本地使用 compose 内的 RustFSS3 兼容仅需暴露并配置AWS_S3_CDN_URL即时通信渠道WECHAT_SYSTEM_PROMPT、TG_SYSTEM_PROMPT、TWITTER_OAUTH2_*可选接入 Telegram/WeChat/Twitter 渠道时填写成本控制PAYMENT_ENABLED、HOURLY_BUDGET可选设置用户每小时最大 LLM 基础成本USDWeb3CDP_*、PRIVY_*、MASTER_WALLET_PRIVATE_KEY、INFURA_API_KEY等可选启用链上能力时配置配置在源码中的加载方式这些环境变量并非 compose 直接消费而是由应用启动时统一加载。intentkit/config/config.py 是配置中心例如数据库连接串由DB_USERNAME/DB_PASSWORD/DB_HOST/DB_PORT/DB_NAME组装其中DB_AUTO_MIGRATE默认true即启动时自动执行 Schema 迁移对应auto_migrate字段REDIS_HOST未配置时会直接抛出RuntimeError(REDIS_HOST is required for Redis)说明 Redis 是硬依赖前端地址APP_BASE_URL默认值为http://localhost:3000与本地模式下前端的监听端口一致。理解这一点有助于排查配置看起来没生效的问题——多数情况下是变量名拼写或未加载.env。启动整套技术栈配置完成后一条命令拉起全部服务docker compose up -d-d表示后台运行。根目录 docker-compose.yml 定义了 8 个服务彼此通过健康检查与依赖关系严格编排服务镜像/构建端口角色dbpostgres:18.1-trixie宿主机15432→ 容器5432主数据库保存 Agent、对话、记忆等业务数据redisredis:8.4-bookworm内部网络缓存与队列Agent 集群的协作通道rustfsrustfs/rustfs:latest9000API/9001控制台S3 兼容对象存储承载头像、图片等媒体资产api源码构建uvicornapp.api:app8000REST API 服务器带--reload热重载autonomous源码构建python -m app.autonomous内部自主 Agent 运行器轮询并执行定时/自主任务scheduler源码构建python -m app.scheduler内部任务调度器frontendfrontend/Dockerfile.devNext.js dev 模式3000Web 控制台telegram/wechatintegrations源码构建内部即时通信渠道接入可选启动几个值得注意的本地模式特性均来自 docker-compose.yml热重载开发体验api服务以--reload启动 uvicorn同时容器把宿主机./intentkit、./app、./public_agents目录挂载进容器修改 Python 代码即时生效frontend服务同样挂载了./frontend/src等目录并设置WATCHPACK_POLLING1000以适配容器内文件监听。.env直接注入所有应用容器将宿主机./.env挂载为/app/.env与 intentkit/config/config.py 的读取逻辑配合改完配置重启对应服务即可。依赖顺序控制api等待db与redis健康后才启动autonomous、scheduler又等待api健康frontend同样依赖api。健康检查脚本见各服务的healthcheck段如scripts/check_heartbeat.py。验证部署是否成功检查容器状态docker compose ps正常状态下所有服务应显示running且健康HEALTHY。若某个服务反复重启多为依赖服务尚未就绪或.env配置缺失。查看日志docker compose logs -f-f持续跟随日志输出。排查 LLM 配置问题时重点关注api容器的输出排查渠道问题时关注telegram/wechat容器。也可以只查看单个服务docker compose logs api访问前端一切就绪后浏览器访问http://localhost:3000前端页面加载正常即代表端到端链路打通——前端3000→ API8000→ Postgres/Redis/RustFS 均已可用。注意不要使用https本地模式没有配置 TLS。停止与数据清理docker compose down停止并移除所有容器与网络。命名卷named volumes会被保留——即postgres_data、rustfs_data、redis_data中的数据Agent 配置、记忆、上传的媒体文件在下次docker compose up -d时依然存在这是刻意设计的持久化行为。如需连同数据卷一起清除、恢复到完全干净的状态docker compose down -v-v会永久删除数据库、对象存储与缓存中的全部数据执行前请确认无需保留。本地模式与生产部署的差异了解差异有助于平滑过渡到正式环境。生产形态参见 deployment/docker-compose.yml 与 docker-compose.md镜像来源本地模式通过build.context: .从源码构建生产模式直接拉取ghcr.io/crestalnetwork/intentkit*预构建镜像。入口与 TLS生产模式额外引入caddy服务根据APP_DOMAIN/TLS_EMAIL自动申请 Lets Encrypt 证书并接管 80/443 端口的反向代理与 Basic Auth入口脚本见 deployment/caddy-entrypoint.sh。热重载本地api使用uvicorn --reload生产模式不带--reload代码变更通过重新拉取镜像发布。升级方式生产环境使用docker compose pull docker compose up -d更新服务本地开发则直接git pull后重建镜像。常见问题速查docker compose up后 api 容器反复重启检查.env中是否配置了至少一个 LLM Provider Key查看docker compose logs api是否有配置加载报错如 Redis 相关的RuntimeError。前端能打开但接口报错确认api服务健康本地模式 API 基地址由 compose 注入NEXT_PUBLIC_API_BASE_URLhttp://localhost:8000与容器端口映射一致。媒体图片无法显示确认rustfs健康AWS_S3_CDN_URLhttp://localhost:9000/static可访问RustFS 控制台位于http://localhost:9001默认凭据minioadmin/minioadmin。端口冲突本地模式占用3000前端、8000API、9000/9001RustFS、15432Postgres 宿主映射如有冲突可修改 docker-compose.yml 中对应ports映射后重启。至此你已在本地完整跑通了 IntentKit 的 Agent 集群可以开始创建 Agent、挂载技能public_agents/目录下已内置 30 预置 Agent 模板并体验 Web 控制台的全部功能。【免费下载链接】intentkitIntentKit is an open-source, self-hosted cloud agent cluster that manages a collaborative team of AI agents for you.项目地址: https://gitcode.com/GitHub_Trending/int/intentkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考