企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 工作流
• Agent 编排
• RAG
• 工具调用
• 后端
• 前端

MateClaw 是一个基于 Spring AI Alibaba 构建的开源多智能体（Multi-Agent）AI 助手平台，内置 MCP 协议、技能系统（Skills）、长期记忆（Memory）与多渠道接入能力。本文是一份面向新手的MateClaw Docker 部署教程：无需手动安装数据库和运行环境，只需 3 条命令，就能把整套私有化 AI 助手跑起来——对话数据、知识库、技能包全部存在你自己的服务器里，彻底告别"数据交给第三方"的顾虑。

为什么选择 Docker 私有化部署 🏠

• 一条命令拉起全栈：MateClaw 官方提供了 docker-compose.yml，一条docker compose up -d同时启动后端服务、PostgreSQL 16 数据库和 SearXNG 搜索引擎，三者通过内部网络互通。
• 数据完全由你掌控：数据库和文件数据都落在 Docker 命名卷里，不对外暴露端口，默认只有应用容器能访问数据库，天然适合团队内网与私有云环境。
• 零环境依赖：官方镜像已内置 JDK 21、Chromium 浏览器（支持网页自动化）、中文 CJK 字体和 PDF 解析工具链（见 mateclaw-server/Dockerfile），构建产物是一个"开箱即用"的完整镜像。

MateClaw Docker 镜像栈组成一览 📦

数据库刻意不映射宿主机端口，临时排查可用docker compose exec postgres psql进入。搜索能力由 SearXNG sidecar 提供，镜像构建时已内置好 docker/searxng/settings.yml，无需额外配置密钥。

3步快速部署：MateClaw Docker 安装步骤 🚀

第一步：克隆 MateClaw 仓库

git clone https://gitcode.com/gh_mirrors/mat/mateclaw cd mateclaw

第二步：准备 .env 配置文件

复制官方示例模板并修改必填密码：

cp .env.example .env

打开.env，只需重点修改两项（留空会导致docker compose up直接报错，防止默认密码流入生产环境）：

• DB_PASSWORD：应用数据库账号密码（建议 16 位以上强密码）
• DB_ADMIN_PASSWORD：PostgreSQL 引导管理员密码
• 生产环境建议同时设置JWT_SECRET（可用openssl rand -base6448生成）

💡模型 API Key 不用在这里填！DashScope、OpenAI、DeepSeek 等供应商密钥在启动后通过管理界面「Settings → Models → Add Provider」添加即可，支持热更新。

第三步：一条命令启动全部服务

docker compose up -d

首次运行会自动执行三个阶段：构建前端（Vue 3 SPA）、用 Maven 编译 Spring Boot 后端、生成带浏览器的运行时镜像。完成后访问：

http://localhost:18080

默认登录账号：admin/admin123（首次登录后建议立即修改密码）。

数据持久化与私有化保障 🔒

• 两个命名卷：postgres_data保存数据库，server_data保存上传的 Wiki 文件、已安装技能及运行产物（挂载到容器/app/data），容器重建不丢数据。
• 最小权限数据库账号：首次初始化时由 docker/postgres/init/10-app-role.sh 自动创建受限应用账号mateclaw，只拥有自己的 schema，非超级用户。
• LLM 密钥不出内网：密钥存储在本机数据库表中，而非散落在配置文件。

常见部署问题与解决 ⚡

Q1：首次构建太慢怎么办？国内网络环境可在.env中取消注释MAVEN_FLAGS=-Paliyun-first，让 Maven 优先走阿里云镜像仓库拉包，速度显著提升。

Q2：以前用 MySQL 版本，能直接升级吗？Docker 栈已切换到 PostgreSQL 16，旧的mysql_data卷不会被新栈读取。升级前请先mysqldump导出备份，或使用 pgloader 等工具跨引擎导入（详见 docker-compose.yml 顶部说明）。

Q3：想访问内网服务时被浏览器工具拦截？默认 SSRF 防护会拦截私有 IP。确需在纯内网使用时，在.env中设置PLAYWRIGHT_ALLOW_PRIVATE_NETWORK=true，公网部署请保持false。

下一步 🎯

部署成功后，推荐按顺序体验：在「Settings → Models」添加模型供应商 → 在「Digital Employees」创建你的第一个智能体 → 在「Channels」接入飞书、微信等消息渠道。更多细节可参考仓库根目录的 README_zh.md，祝你顺利落地属于自己的 MateClaw 第二大脑！

• 人工智能
• AI Agent
• Agent 工作流
• Agent 编排
• RAG
• 工具调用
• 后端
• 前端