# 部署配置

<cite>
**本文档中引用的文件**
- [config.yaml](file://manifest/config/config.yaml)
- [Dockerfile](file://manifest/docker/Dockerfile)
- [docker-compose.yml](file://manifest/docker/docker-compose.yml)
- [docker-compose-local.yaml](file://manifest/docker/docker-compose-local.yaml)
- [install.sh](file://manifest/docker/install.sh)
- [kustomization.yaml](file://manifest/deploy/kustomize/base/kustomization.yaml)
- [kustomization.yaml](file://manifest/deploy/kustomize/overlays/develop/kustomization.yaml)
- [deployment.yaml](file://manifest/deploy/kustomize/base/deployment.yaml)
- [deployment.yaml](file://manifest/deploy/kustomize/overlays/develop/deployment.yaml)
- [configmap.yaml](file://manifest/deploy/kustomize/overlays/develop/configmap.yaml)
- [Makefile](file://Makefile)
- [hack.mk](file://hack/hack.mk)
- [.drone.yml](file://.drone.yml)
- [cron.go](file://utility/cron/cron.go)
</cite>

## 更新摘要

**变更内容**

- 更新了Docker镜像仓库地址，从旧地址迁移至 `git.oceanpay.cc`
- 调整了京东支付状态监控任务的执行频率，由每10秒一次改为每30秒一次
- 新增了每分钟执行的京东订单支付状态检查任务
- 相应更新了CI/CD配置文件中的Docker登录和推送指令

## 目录
1. [配置管理](#配置管理)
2. [Docker容器化部署](#docker容器化部署)
3. [自动化部署脚本](#自动化部署脚本)
4. [多环境配置与部署](#多环境配置与部署)
5. [Kustomize配置管理](#kustomize配置管理)
6. [部署检查清单与最佳实践](#部署检查清单与最佳实践)

## 配置管理

`manifest/config/config.yaml` 文件是系统的核心配置文件，包含了服务器、数据库、缓存、安全等关键配置项。该文件采用YAML格式，结构清晰，便于维护。

**服务器配置**部分定义了服务监听地址、日志输出、访问控制等参数。`server.address` 指定服务监听端口，默认为":12401"。日志配置中，`logStdout` 控制是否输出到终端，`errorLogEnabled` 决定是否记录异常日志，`accessLogEnabled` 控制访问日志的开启状态。

**数据库配置**支持多数据源，当前配置了`default`和`v1`两个MySQL连接。每个数据源包含连接字符串、调试模式、字符集、连接池参数等。`maxOpen` 和 `maxIdle` 分别控制最大打开连接数和最大闲置连接数，对系统性能有重要影响。

**Redis配置**为缓存系统提供连接参数，包括地址、数据库编号、超时设置和最大活跃连接数。`idleTimeout` 和 `maxConnLifetime` 等参数确保连接的有效性和资源的合理利用。

**安全配置**包含加密密钥和令牌设置。`secret` 部分定义了前后端加密的密钥和初始化向量（IV），`token` 部分配置了令牌的超时时间、刷新策略和存储方式。

**第三方服务集成**配置了OAuth认证、通知平台等外部服务的连接信息，如天猫游戏网关、Agiso应用凭证等。

**Section sources**
- [config.yaml](file://manifest/config/config.yaml#L1-L104)

## Docker容器化部署

### Dockerfile构建过程

`manifest/docker/Dockerfile` 文件定义了kami_backend服务的容器镜像构建流程，采用多阶段构建策略以减小最终镜像体积。

构建过程分为两个阶段：**构建阶段**使用 `golang:1.25-alpine` 作为基础镜像，设置Go模块代理，执行依赖整理和二进制编译。**运行阶段
**基于轻量级的 `alpine:latest` 镜像，复制编译好的二进制文件和必要的资源文件（如静态资源和配置文件）。

运行阶段还配置了时区为亚洲/上海，安装了curl工具用于健康检查，并设置了 `HEALTHCHECK` 指令，通过curl命令定期检查服务的健康状态。容器暴露12401端口，通过CMD指令启动主程序。

### docker-compose编排配置

项目提供了两个docker-compose配置文件：`docker-compose.yml` 用于生产环境，`docker-compose-local.yaml` 用于本地开发。

**生产环境配置** (`docker-compose.yml`) 使用预构建的镜像，通过环境变量 `${DRONE_BRANCH}${DRONE_BUILD_NUMBER}` 实现版本控制。容器端口映射为 `127.0.0.1:22401:12401`，限制外部访问。通过volumes将日志目录和配置目录挂载到宿主机，实现日志持久化和配置热更新。容器连接到外部网络 `1panel-network`。

**本地开发配置** (`docker-compose-local.yaml`) 使用本地构建方式，直接从项目根目录构建镜像，便于开发调试。端口映射为 `127.0.0.1:12401:12401`，方便本地访问。同样挂载了必要的资源文件。

```mermaid
graph TD
A[Docker构建阶段] --> B[golang:1.25-alpine]
B --> C[复制源码]
C --> D[go mod tidy]
D --> E[go build]
E --> F[生成二进制]
G[Docker运行阶段] --> H[alpine:latest]
H --> I[复制二进制]
I --> J[复制资源文件]
J --> K[设置时区]
K --> L[安装curl]
L --> M[HEALTHCHECK]
M --> N[CMD启动]
F --> I
```

**Diagram sources**
- [Dockerfile](file://manifest/docker/Dockerfile#L1-L41)
- [docker-compose.yml](file://manifest/docker/docker-compose.yml#L1-L19)
- [docker-compose-local.yaml](file://manifest/docker/docker-compose-local.yaml#L1-L20)

**Section sources**
- [Dockerfile](file://manifest/docker/Dockerfile#L1-L41)
- [docker-compose.yml](file://manifest/docker/docker-compose.yml#L1-L19)
- [docker-compose-local.yaml](file://manifest/docker/docker-compose-local.yaml#L1-L20)

## 自动化部署脚本

### Makefile自动化构建

`Makefile` 提供了标准化的构建和部署命令。通过包含 `hack/hack.mk` 文件，继承了GoFrame框架的构建能力。

关键目标包括：
- `up`: 更新GoFrame框架和CLI工具
- `build`: 编译二进制文件
- `dao`: 生成数据访问对象(DAO)代码
- `image`: 构建Docker镜像，自动获取Git标签作为镜像版本
- `image.push`: 构建并推送镜像到仓库
- `deploy`: 部署应用到Kubernetes环境

`image` 目标通过Git描述自动生成镜像标签，支持脏工作区标记，确保版本可追溯。

### install.sh一键部署脚本

`manifest/docker/install.sh` 是一个功能完整的自动化部署脚本，支持多个kami系列应用的部署。

脚本流程：
1. 用户选择要部署的应用
2. 克隆或更新代码仓库
3. 停止并删除现有容器
4. 停止所有Docker容器
5. 根据应用类型使用相应的docker-compose文件构建并启动服务
6. 重启所有kami_前缀的容器
7. 清理临时文件和悬空镜像
8. 自我删除

该脚本实现了从代码拉取到服务启动的完整自动化流程，大大简化了部署操作。

```mermaid
flowchart TD
Start([开始]) --> SelectApp["选择应用 (1-7)"]
SelectApp --> CheckRepo{"仓库存在?"}
CheckRepo --> |否| CloneRepo["克隆代码"]
CheckRepo --> |是| UpdateRepo["更新代码"]
CloneRepo --> CdRepo
UpdateRepo --> CdRepo
CdRepo --> StopContainer["停止现有容器"]
StopContainer --> StopAll["停止所有容器"]
StopAll --> BuildStart["构建并启动服务"]
BuildStart --> RestartKami["重启kami_容器"]
RestartKami --> Cleanup["清理临时文件"]
Cleanup --> RemoveDangling["删除悬空镜像"]
RemoveDangling --> SelfDelete["自我删除"]
SelfDelete --> End([完成])
```

**Diagram sources**
- [Makefile](file://Makefile#L1-L6)
- [hack.mk](file://hack/hack.mk#L1-L75)
- [install.sh](file://manifest/docker/install.sh#L1-L144)

**Section sources**
- [Makefile](file://Makefile#L1-L6)
- [hack.mk](file://hack/hack.mk#L1-L75)
- [install.sh](file://manifest/docker/install.sh#L1-L144)

## 多环境配置与部署

系统通过不同的配置文件和部署策略支持开发、测试、生产等多环境部署。

**开发环境**使用 `docker-compose-local.yaml`，直接从本地代码构建镜像，便于快速迭代。配置文件中的服务地址通常指向本地或开发服务器。

**测试环境**可能使用 `install-test.sh` 脚本（未在文件列表中显示，但命名暗示存在），配置指向测试数据库和第三方服务沙箱环境。

**生产环境**使用 `docker-compose.yml`，从镜像仓库拉取指定版本的镜像，确保部署一致性。配置文件中的服务地址指向生产环境的真实服务。

环境差异主要体现在：
- 镜像来源（本地构建 vs 仓库拉取）
- 数据库连接信息
- 第三方服务API密钥
- 日志级别和输出位置
- 资源限制和副本数量

通过环境变量和不同的docker-compose文件，实现了配置与代码的分离，确保了环境间的一致性和安全性。

**Section sources**
- [docker-compose.yml](file://manifest/docker/docker-compose.yml#L1-L19)
- [docker-compose-local.yaml](file://manifest/docker/docker-compose-local.yaml#L1-L20)
- [config.yaml](file://manifest/config/config.yaml#L1-L104)

## Kustomize配置管理

Kustomize用于Kubernetes环境下的配置管理，通过基础配置和环境覆盖实现配置的复用和差异化。

**基础配置**位于 `manifest/deploy/kustomize/base/` 目录，包含 `deployment.yaml` 和 `service.yaml` 两个资源文件，以及 `kustomization.yaml` 定义文件。基础配置定义了应用的基本部署结构，如副本数、容器镜像名称等。

**环境覆盖**位于 `manifest/deploy/kustomize/overlays/` 目录，当前有 `develop` 开发环境覆盖。覆盖配置通过 `kustomization.yaml` 引用基础配置，并添加或修改特定于环境的设置。

`develop/kustomization.yaml` 文件：
- 通过 `resources` 引用基础配置和额外的 `configmap.yaml`
- 使用 `patchesStrategicMerge` 对基础Deployment进行策略性合并补丁
- 设置命名空间为 `default`

`develop/configmap.yaml` 定义了一个ConfigMap，用于覆盖基础配置中的 `config.yaml` 内容，如修改服务器监听端口为8000。

`develop/deployment.yaml` 补丁文件将容器镜像修改为 `template-single:develop`，实现开发环境的特定版本部署。

这种分层配置管理方式实现了"一次编写，多处部署"的目标，提高了配置的可维护性和一致性。

```mermaid
graph TD
subgraph Base
B_Kustom["kustomization.yaml"]
B_Deploy["deployment.yaml"]
B_Service["service.yaml"]
end
subgraph Overlays
subgraph Develop
D_Kustom["kustomization.yaml"]
D_Config["configmap.yaml"]
D_Patch["deployment.yaml"]
end
end
B_Kustom --> D_Kustom
B_Deploy --> D_Patch
D_Kustom --> D_Config
D_Kustom --> D_Patch
```

**Diagram sources**
- [kustomization.yaml](file://manifest/deploy/kustomize/base/kustomization.yaml#L1-L9)
- [kustomization.yaml](file://manifest/deploy/kustomize/overlays/develop/kustomization.yaml#L1-L15)
- [deployment.yaml](file://manifest/deploy/kustomize/base/deployment.yaml#L1-L22)
- [deployment.yaml](file://manifest/deploy/kustomize/overlays/develop/deployment.yaml#L1-L10)
- [configmap.yaml](file://manifest/deploy/kustomize/overlays/develop/configmap.yaml#L1-L15)

**Section sources**
- [kustomization.yaml](file://manifest/deploy/kustomize/base/kustomization.yaml#L1-L9)
- [kustomization.yaml](file://manifest/deploy/kustomize/overlays/develop/kustomization.yaml#L1-L15)
- [deployment.yaml](file://manifest/deploy/kustomize/base/deployment.yaml#L1-L22)
- [deployment.yaml](file://manifest/deploy/kustomize/overlays/develop/deployment.yaml#L1-L10)
- [configmap.yaml](file://manifest/deploy/kustomize/overlays/develop/configmap.yaml#L1-L15)

## 部署检查清单与最佳实践

### 部署前检查清单

- [ ] 确认 `config.yaml` 中的数据库连接信息正确
- [ ] 验证Redis服务可访问
- [ ] 检查第三方服务API密钥有效
- [ ] 确认日志目录有写入权限
- [ ] 验证Docker和docker-compose已安装
- [ ] 确保目标端口未被占用

### 部署后验证清单

- [ ] 检查容器状态为running
- [ ] 验证服务健康检查通过
- [ ] 测试API端点可访问
- [ ] 检查日志文件正常生成
- [ ] 验证数据库连接正常
- [ ] 确认缓存服务工作正常

### 最佳实践

**安全实践**
- 生产环境禁用 `accessLogEnabled`
- 定期轮换 `secret` 中的加密密钥
- 使用专用的数据库用户，限制权限
- 敏感信息通过环境变量注入，而非硬编码
- CI/CD流程中使用新的Docker仓库地址 `git.oceanpay.cc`

**性能实践**
- 根据实际负载调整 `database.maxOpen` 连接池大小
- 合理设置 `redis.maxActive` 避免资源耗尽
- 监控连接池使用情况，及时发现瓶颈
- 京东支付状态监控任务已调整为每30秒执行一次，减少系统负载

**运维实践**
- 使用 `Makefile` 的 `image.push` 目标确保镜像版本可追溯
- 定期清理悬空镜像和停止的容器
- 备份重要配置文件
- 建立部署回滚机制
- 新增了每分钟执行的京东订单支付状态检查任务，确保订单状态及时更新

**开发实践**
- 本地开发使用 `docker-compose-local.yaml`
- 避免在代码中硬编码环境相关配置
- 使用Kustomize管理Kubernetes配置差异
- 通过 `install.sh` 脚本实现一键部署

**Section sources**
- [config.yaml](file://manifest/config/config.yaml#L1-L104)
- [Dockerfile](file://manifest/docker/Dockerfile#L1-L41)
- [docker-compose.yml](file://manifest/docker/docker-compose.yml#L1-L19)
- [install.sh](file://manifest/docker/install.sh#L1-L144)
- [kustomization.yaml](file://manifest/deploy/kustomize/base/kustomization.yaml#L1-L9)
- [.drone.yml](file://.drone.yml#L1-L46)
- [cron.go](file://utility/cron/cron.go#L1-L65)