kratos-shop

kratos 框架写商品微服务

本项目是一个使用 Kratos 框架创建的很简单的微服务商城项目。

注: 本项目中但凡 kratos 提供包,就不会自己封装第三方的包。

主要是为了学习 kratos 如何使用,尤其各种中间件之间的调用,包括微服务的一些技术点。

项目具体目录结构初步设计如下:

|-- kratos-shop
    |-- service
        |-- user // 用户服务 grpc
        |-- goods // 商品服务 grpc
        |-- cart // 购物车服务 grpc
        |-- order // 订单服务 grpc
        |-- inventory // 库存服务服务 grpc
    |-- shop // shop 商城服务 http (后期会考虑把订单单独拆出来)
        ├── api  // 商城 api
        │   ├── service
        │   │   └── user
        │   │       └── v1 // 用户服务的 proto
        │   │   └── goods
        │   │       └── v1 // 商品服务的 proto
        │   │
        │   └── shop
        │       └── v1
        │           ├── error_reason.proto
        │           ├── shop.proto
        │── cmd
        │── internal
        │.....
    |-- admin // 后端管理系统 web

服务启动

项目一共包含 8 个应用服务：user、goods、cart、order、inventory、payment、shop、admin。下面介绍三种启动方式，可以按场景选择。

方式一：Docker 一键启动（本地最省事，推荐）

环境需要 Docker Desktop / OrbStack，在项目根目录执行：

make up

等价于：

docker compose -f deploy/docker-compose.yml up -d --build

该命令会一次性启动全部 8 个应用服务，以及它们依赖的基础设施（Postgres、Redis、RabbitMQ、Consul、Elasticsearch、Jaeger）和可观测性组件（Prometheus、Grafana、Loki、Promtail、Traefik 网关）。

启动完成后可访问：

停止并清理环境：

make down

注意：make up 会占用 5432/6379/5672/8500/9200/80 等端口，如果本机已经有服务占用这些端口，请先停掉。

方式二：本地手动启动（适合开发调试）

手动方式适合需要看单个服务日志、打断点调试的场景。需要 Go 1.26.5 和 Docker。

1. 只启动基础设施：

make infra-up

等价于：

docker compose -f deploy/docker-compose.yml up -d postgres redis rabbitmq consul elasticsearch jaeger

1. 初始化数据库与 Mock 数据（脚本幂等，可重复执行）：

./scripts/init-db.sh

1. 构建全部服务：

make build

1. 分别启动各个服务。建议每个服务开一个终端，先启动 6 个 gRPC 服务，再启动 shop 和 admin：

cd service/user && ./bin/user -conf configs
cd service/goods && ./bin/goods -conf configs
cd service/cart && ./bin/cart -conf configs
cd service/order && ./bin/order -conf configs
cd service/inventory && ./bin/inventory -conf configs
cd service/payment && ./bin/payment -conf configs
cd shop && ./bin/shop -conf configs
cd admin && ./bin/admin -conf configs

1. 验证服务是否正常：

curl -X POST http://127.0.0.1:8097/api/users/login \
  -H 'Content-Type: application/json' \
  -d '{"mobile":"13800138000","password":"12345678"}'

也可以在 Consul UI（http://127.0.0.1:8500/ui）确认 8 个服务都已注册。

停止基础设施：

make infra-down

方式三：微服务独立部署（多服务器 / 生产环境）

微服务拆分的目的就是可以按服务独立部署：每个服务都是一个独立二进制，可以运行在不同的服务器上，通过同一个 Consul 互相发现和调用。

1. 构建某个服务：

cd service/user
make build

如果目标服务器不是当前系统，可以先交叉编译：

cd service/user
GOOS=linux GOARCH=amd64 make build

1. 把 bin/user 和 configs/ 目录一起拷贝到目标服务器。

2. 修改目标服务器上的配置：

3. configs/config.yaml：把数据库、Redis、RabbitMQ、Elasticsearch、Jaeger 地址改成实际可达的地址（不要用 127.0.0.1，除非依赖就在本机）

4. configs/registry.yaml：把 consul.address 改成 Consul 所在服务器的地址，所有服务必须注册到同一个 Consul

5. 启动服务：

./bin/user -conf configs

其他服务（goods、cart、order、inventory、payment、shop、admin）按同样方式部署。

1. 验证：在 Consul UI（http://:8500/ui）里应能看到已注册的服务。服务之间通过 discovery:///shop.xxx.service 调用，只要 Consul 配置一致，服务跑在哪台机器上不影响调用关系。

各服务默认端口：

更详细的多服务器部署说明见 docs/development.md。

运营后台前端（可选）

web/admin 是基于 Ant Design Pro v6（Umi Max 4 + React 19 + Ant Design 6）的运营后台，菜单顺序为首页 → 用户管理 → 订单管理 → 商品管理 → 商品分类 → 权限管理，登录后默认进入首页看板。当前支持首页数据看板（用户数 / 订单量 / 成交额 / 近 30 天趋势 / 状态分布 / 热销商品）、用户管理（用户列表 / 收货地址管理）、订单管理（列表 / 详情 / 发货 / 退款）、商品管理（分类 / 品牌 / SKU 编码搜索、商品详情含 SKU 与图片、新增 / 上下架 / 删除）、商品分类管理（新增 / 编辑 / 删除）和权限管理（角色权限点配置，前端按钮级隐藏）：

cd web/admin
npm install
npm run dev

开发环境访问 http://localhost:8000，/api/* 自动代理到 admin BFF（127.0.0.1:9099）。

需要演示数据时执行（100 个用户、50 个商品、每人 3~5 笔模拟订单）：

make seed-demo

可观测性与辅助组件

make up 启动的整套环境里，除了 8 个应用服务，还包含以下组件：

• Prometheus：已自动抓取 8 个服务的 /metrics（user 9101 ~ admin 9108）以及 Postgres、Redis、Consul，可在 Status → Targets 确认抓取正常。
• Grafana：预置了 Prometheus 和 Loki 两个数据源，登录后可在 Explore 中查指标或日志。
• RabbitMQ：order/payment 发布消息，goods/inventory/order 消费消息；管理台可查看队列、连接和消息积压。
• Jaeger：各服务通过 Collector（14268）上报 trace，UI 中按 Service 搜索即可查看调用链。
• Traefik：localhost 路由到商城 BFF，admin.localhost 路由到后台管理（需在 /etc/hosts 添加 127.0.0.1 admin.localhost）。
• Loki + Promtail：自动采集所有容器日志，Grafana Explore 中选择 Loki 数据源，可按 container 或 service 标签过滤。

默认账号仅适用于本地环境，公网部署请务必修改密码并限制管理端口暴露。

更详细的组件说明与验证方法见 docs/development.md。

演示账号

• 普通用户：13800138000 / 12345678
• 管理员：13501167215 / 12345678

以上账号由 sql/ 初始化脚本写入，仅用于本地演示。

支付说明

service/payment 目前为本地模拟支付（channel: mock），不会发起真实扣款，适合学习和联调。如需接入真实渠道（支付宝、微信支付、Stripe 等），需要自行扩展支付服务。

更多文档

• 项目首页：GitHub Pages 项目首页与 API 文档
• 配置说明：Demo 配置与 config.local.yaml 本地覆盖机制
• 架构与微服务关系：架构图、服务职责、部署形态
• 数据库说明：连接信息、初始化与迁移
• 本地开发指南：环境要求、启动、验证、可观测性
• Kubernetes 部署：Kustomize 清单与部署步骤
• OpenAPI 接口文档：各服务 openapi.yaml 可用 Swagger UI / Redoc 查看，例如 npx @redocly/cli preview-docs shop/openapi.yaml

• 有任何建议，请扫码添加我微信进行交流。

技术栈、快速开始与更详细的说明见 docs/README.md。