本机环境
2 分钟阅读
准备环境
当前模板以 Go 1.25.13 为基线。安装 Git、Make、curl、unzip 与 Go，检查版本：
go version
git --version
make --version
将 go env GOPATH 返回目录中的 bin 加入 PATH。Go Modules 项目无需放在 GOPATH 内，依赖的 Proto include 仍按生成脚本约定放在 GOPATH 的 src 下。
export PATH="$(go env GOPATH)/bin:$PATH"
从 CLI Releases 选择与目标系统/架构一致的稳定版，安装为 grpc-kit-cli；核对发布版本与版本基线。源码构建请在 CLI 仓库运行 make build 并选择匹配平台的构建物。
grpc-kit-cli version --short
创建项目
grpc-kit-cli new -t service -p opsaid -s test1 --output ./test1
cd test1
new 先完成临时目录渲染，再发布目标目录；目标已存在时拒绝覆盖。--output 是路径，-o 是组织名；不要把两者混用。已有项目使用迁移命令。
安装生成工具
在生成的项目内执行：
make protoc
make protoc-gen-go
make protoc-gen-go-grpc
make protoc-gen-grpc-gateway
make protoc-gen-openapiv2
版本由项目的 scripts/binaries.sh 固定。macOS 使用 osx 构建物，Linux 使用 linux 构建物，arm64 对应 aarch_64。不要混用旧教程的 Linux 二进制与 macOS 平台。
Proto include 不是 Go module 下载的副产物。还需安装 grpc-kit/api、googleapis 和 grpc-gateway 的 Proto 源码。以下 API tag 与 googleapis commit 沿用 CLI 仓库的模板兼容流水线基线；更新它们时必须重新验证：
TASK_GOPATH="$(go env GOPATH)"
mkdir -p "$TASK_GOPATH/src/github.com/grpc-kit" "$TASK_GOPATH/src/github.com/googleapis" "$TASK_GOPATH/src/github.com/grpc-ecosystem"
git clone --depth 1 --branch v0.3.1 https://github.com/grpc-kit/api.git "$TASK_GOPATH/src/github.com/grpc-kit/api"
git clone https://github.com/googleapis/googleapis.git "$TASK_GOPATH/src/github.com/googleapis/googleapis"
git -C "$TASK_GOPATH/src/github.com/googleapis/googleapis" checkout e0d0106516a5c613510533821e4508bc6c943b11
git clone --depth 1 --branch v2.30.0 https://github.com/grpc-ecosystem/grpc-gateway.git "$TASK_GOPATH/src/github.com/grpc-ecosystem/grpc-gateway"
目标目录存在时应检查已有 checkout 的 ref，避免覆盖。当前 API 源码 VERSION 为 v0.4.1，并不等于此基线已改为 v0.4.1。
配置、生成与运行
检查 config/app-dev-local.yaml 中的服务地址、安全配置和依赖开关；按本机实际情况关闭不使用的数据库、Redis、工作流等能力。配置说明见配置总览。
make generate
make test
make build
make run
make run 使用 config/app-dev-local.yaml。该开发配置通常被 Git 忽略，CI 或新 checkout 必须自行提供。生成过程会更新生成文件、依赖及版本信息，完成后检查 git diff。
服务访问测试
默认 HTTP 示例地址为 127.0.0.1:8080，请按配置调整。
curl -fsS http://127.0.0.1:8080/ping
curl -fsS 'http://127.0.0.1:8080/api/healthz?service=test1.v1.opsaid'
curl -fsS http://127.0.0.1:8080/version
curl -fsS http://127.0.0.1:8080/metrics
健康查询参数是 service，值对应 services.service_code。/ping 只证明 HTTP 入口可达；/api/healthz 经过业务 Gateway/RPC，但模板实现只比较服务名，不验证数据库或缓存。生产 readiness 需按部署检查补足。
/openapi-spec/ 需启用相应前端托管；/api/demo 的访问凭据由 security 配置决定。示例静态账号仅用于本地开发。
来源：当前 CLI 模板。上述命令是操作步骤，本轮未执行应用运行测试。