【实战】HiMarket本地化部署指南

第1章部署概述

HiMarket是一套全栈服务，完整部署需依赖5大核心基础组件 ，所有组件协同工作支撑服务运行；官方提供两种标准化部署方式 ，且均通过交互式install.sh脚本实现一键配置、初始化，无需手动繁琐配置，极大降低部署门槛。

1.1🌐 HiMarket 核心架构全景图

（理解组件协作关系的关键）
用户/开发者
Higress AI 网关
HiMarket Server
MySQL 数据库
Nacos 配置中心
Redis 缓存
AI 模型服务
HiMarket Admin 管理后台
HiMarket Frontend 开发者门户
管理操作
应用发布/调用

原理说明 ：

Higress 作为 AI 网关（核心枢纽），统一处理所有请求路由、鉴权及 AI 模型调用；

HiMarket 服务（Server/Admin/Frontend/Sandbox）依赖 Nacos 配置中心动态获取服务地址，通过 MySQL 存储业务数据，Redis 缓存高频请求。
所有组件通过 Docker Compose 或 Helm 自动编排，实现一键部署。

1.2 完整部署核心组件

HiMarket部署必须包含以下组件，缺一不可：

MySQL：核心数据库服务，负责业务数据的持久化存储
Nacos：配置中心+服务发现组件，统一管理服务配置、实现服务注册发现
Higress：AI网关，作为服务流量统一入口
Redis：缓存服务，提升数据读写效率
HiMarket：核心业务载体，包含Server（后端服务）、Admin（管理后台）、Frontend（开发者门户）、Sandbox（沙箱）四大模块

1.3📌 部署方式概览

部署类型	适用场景	核心优势	依赖环境
Docker Compose	本地开发/单机测试	0配置启动，环境隔离性好	Docker, Docker Compose, curl, jq
Helm（K8s）	生产环境/集群部署	高可用、自动扩缩容、云原生集成	kubectl, Helm, python3, curl, jq

统一管理逻辑 ：两种方式均使用 install.sh 脚本，交互式引导完成所有配置 （镜像版本、密码、AI 模型等），非交互模式通过 ~/himarket-install.env 复用配置。

第2章环境依赖

部署前需提前安装对应依赖，两种部署方式依赖略有差异，基础通用依赖+专属依赖如下：

基础通用依赖：curl（网络请求工具）、jq（JSON解析工具）
Docker Compose 部署专属依赖：Docker、Docker Compose
Helm（K8s）部署专属依赖：kubectl（已连接K8s集群）、helm、python3

第3章 AI 辅助部署（推荐）

如果担心部署过程中遇到环境兼容性、配置错误等问题，推荐使用AI编程工具辅助部署，AI可自动识别环境问题、解决部署报错，零门槛完成部署。

操作步骤

先克隆项目到本地
打开Openclaw、Cursor、Qoder、Claude Code等AI Coding工具
输入指令：阅读 deploy 目录下的部署文档，帮我用 Docker Compose 部署 HiMarket
AI会自动完成环境检测、配置修改、部署执行

详细官方部署规则可参考：部署文档

第4章 Docker Compose 部署（本地开发/单机部署）

Docker Compose是最常用的部署方式 ，适合本地调试、个人单机使用，通过install.sh脚本完成全栈服务（HiMarket、Higress、Nacos、MySQL）一键部署。

4.1 前置条件

已安装：Docker、Docker Compose、curl、jq

bash 复制代码

docker     # 容器引擎
docker compose  # 容器编排工具
curl       # 网络请求工具
jq         # JSON 处理工具

4.2 交互式部署（官方推荐）

脚本会逐步引导完成所有配置（镜像选择、密码设置、AI模型配置等），无需手动修改配置文件，新手首选：

bash 复制代码

git clone https://github.com/higress-group/himarket.git
cd himarket/deploy/docker
./install.sh  # 脚本将引导完成：镜像选择、密码设置、AI 模型配置等

原理：脚本通过 read 命令交互式收集配置，自动写入 ~/himarket-install.env，后续升级/卸载无需重复配置。

如下图所示：

4.3 非交互模式（适用于CI/CD自动化部署）

适合自动化流水线部署，无需人工交互，通过预编辑配置文件实现静默部署：

bash 复制代码

# 1. 复制配置模板到用户目录
cp .env.example ~/himarket-install.env
# 2. 编辑配置文件，按需修改参数
# 3. 执行非交互部署命令
./install.sh -n

🛠️ 管理操作

操作	命令	说明
卸载	`./install.sh --uninstall`	清理所有容器、网络、卷数据
升级	重新运行 `./install.sh`	自动检测现有部署并提供升级选项
查看日志	`docker compose logs -f`	实时跟踪容器日志

4.4🌐 服务访问地址（部署后立即可用）

服务名称	主机端口	访问地址	说明
HiMarket Admin	5174	http://localhost:5174	管理后台（用户/权限管理）
HiMarket Frontend	5173	http://localhost:5173	开发者门户（应用发布/调用）
HiMarket Server	8081	http://localhost:8081	后端 API 服务（核心业务）
Nacos	8848	http://localhost:8848/nacos	配置中心（动态配置管理）
Higress Console	8001	http://localhost:8001	Higress 网关控制台
Higress Gateway	8082	http://localhost:8082	网关 HTTP 入口（所有请求入口）
MySQL	3306	-	数据库服务（存储业务数据）
Redis	6379	-	缓存服务（加速高频请求）

关键设计 ：
Higress Gateway (8082) 作为统一入口 ，将请求路由到 HiMarket Server（8081）、AI 模型服务等，实现服务解耦。

如下图所示：

第5章 Helm（Kubernetes）部署（生产环境/集群部署）

适合企业生产环境、多节点集群部署，兼容Kubernetes生态，同样通过install.sh脚本实现自动化部署。

5.1✅ 前置条件

bash 复制代码

kubectl          # Kubernetes 命令行工具（需已连接集群）
helm             # Helm 包管理器
python3          # 用于配置脚本
curl, jq         # 与 Docker 部署相同

5.2🔧 部署步骤

1️⃣ 交互式部署（推荐）

bash 复制代码

git clone https://github.com/higress-group/himarket.git
cd himarket/deploy/helm
./install.sh  # 脚本引导配置（同 Docker 方式）

2️⃣ 非交互模式

bash 复制代码

cp .env.example ~/himarket-install.env
nano ~/himarket-install.env  # 修改配置
./install.sh -n

⚙️ 关键配置说明

默认命名空间 ：himarket（Helm 部署时自动创建）
服务类型 ：Admin/Frontend 默认使用 LoadBalancer（K8s 服务类型，暴露公网 IP）
配置复用 ：~/himarket-install.env 同 Docker 部署，升级时自动加载

原理：Helm 通过 values.yaml 模板化管理 Kubernetes 资源，install.sh 生成最终配置文件，实现声明式部署。

5.3🛠️ AI 辅助部署（解决环境兼容性问题）

推荐场景 ：本地环境配置复杂（如 Docker 版本冲突、依赖缺失）
操作流程：

Clone 项目：git clone https://github.com/higress-group/himarket.git

在 Cursor/Qoder/Claude Code 等 AI 工具中输入：
阅读 deploy 目录下的部署文档，帮我用 Docker Compose 部署 HiMarket

AI 自动执行 ：

识别本地环境（Docker 版本、依赖缺失）

生成修复脚本（如 apt install curl jq）

生成配置文件（~/himarket-install.env）

执行 install.sh 无阻塞部署
优势：自动解决环境兼容性问题，避免手动排查 80% 的部署失败原因。

第6章服务卸载与升级

6.1 服务卸载

两种部署方式通用卸载命令，执行后会自动清理所有服务、数据、配置：

bash 复制代码

# 进入对应部署目录（docker/helm）后执行
./install.sh --uninstall

6.2 服务升级

无需额外操作，重新运行install.sh脚本即可 ：

脚本会自动检测已有部署环境，直接提供升级选项，一键完成版本升级。

第7章配置说明

install.sh脚本的配置逻辑标准化，所有配置可复用、可追溯：

交互模式：脚本会逐步引导配置所有项（镜像、数据库密码、服务凭证、默认用户、AI模型等）
配置持久化 ：所有配置自动保存到~/himarket-install.env，后续升级时自动复用，无需重复配置
配置模板 ：.env.example是官方标准配置模板，包含所有可配置项及默认值，专门用于非交互模式
日志记录 ：部署日志自动保存到~/himarket-install.log，方便排查问题

❓ 常见问题排查指南

问题类型	解决方案
部署失败	`cat ~/himarket-install.log`（查看详细日志）
需跳过部分初始化	- 交互模式：脚本提供"跳过"选项- 非交互模式：设置环境变量 `SKIP_AI_MODEL_INIT=true`
重试初始化钩子	执行钩子脚本：`bash hooks/post_ready.d/your_hook.sh`（位于部署目录）
查看容器日志	`docker compose logs -f`（Docker）`kubectl logs -n himarket <pod-name>`（Helm）

✅ 总结：部署决策树

本地开发/测试
生产环境/集群
开始部署
目标环境?
Docker Compose
Helm
运行 ./install.sh 交互式部署
运行 ./install.sh 交互式部署
AI 辅助部署推荐
自动解决环境问题
成功访问 http://localhost:5174

核心原则：

优先用交互式脚本 → 自动化配置，降低出错率

AI 辅助解决环境问题 → 无需手动排查依赖

配置复用机制 → ~/himarket-install.env 确保升级一致性

端口设计清晰 → 服务隔离，避免冲突

核心组件：HiMarket依赖MySQL、Nacos、Higress、Redis四大基础服务，自身包含4大业务模块；

部署核心 ：两种方式均用install.sh脚本，支持交互/非交互模式，配置自动保存复用；

快速上手：本地部署首选Docker Compose交互式脚本，AI工具可解决环境兼容问题；

运维便捷：一键卸载、一键升级，日志+钩子脚本让问题排查更简单。

附录：常用命令

	说明	命令/代码
查找容器	先找到你的容器 ID 或名字	`docker ps
进入容器	进入容器内部（假设容器名叫 `mysql`）	`docker exec -it mysql /bin/bash`
登录 MySQL	在容器内部尝试直接登录（通常 root@localhost 免密或空密码）	`mysql -u root`
查看密码	查看容器的环境变量，寻找 `MYSQL_ROOT_PASSWORD`	`docker inspect himarket-mysql
停止mysql	停止容器的mysql	`docker stop himarket-mysql`

如下图所示：

【实战】HiMarket本地化部署指南

第1章 部署概述

1.1🌐 HiMarket 核心架构全景图

1.2 完整部署核心组件

1.3📌 部署方式概览

第2章 环境依赖

第3章 AI 辅助部署（推荐）

操作步骤

第4章 Docker Compose 部署（本地开发/单机部署）

4.1 前置条件

4.2 交互式部署（官方推荐）

4.3 非交互模式（适用于CI/CD自动化部署）

🛠️ 管理操作

4.4🌐 服务访问地址（部署后立即可用）

第5章 Helm（Kubernetes）部署（生产环境/集群部署）

5.1✅ 前置条件

5.2🔧 部署步骤

1️⃣ 交互式部署（推荐）

2️⃣ 非交互模式

⚙️ 关键配置说明

5.3🛠️ AI 辅助部署（解决环境兼容性问题）

第6章 服务卸载与升级

6.1 服务卸载

6.2 服务升级

第7章 配置说明

❓ 常见问题排查指南

✅ 总结：部署决策树

附录：常用命令

第1章部署概述

第2章环境依赖

第6章服务卸载与升级

第7章配置说明