# 容器化部署

<cite>
**本文档引用的文件**
- [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)
- [install-simple.sh](file://manifest/docker/install-simple.sh)
- [install-one.sh](file://manifest/docker/install-one.sh)
- [install-test.sh](file://manifest/docker/install-test.sh)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)
</cite>

## 目录
1. [Dockerfile详解](#dockerfile详解)
2. [docker-compose配置分析](#docker-compose配置分析)
3. [部署脚本说明](#部署脚本说明)
4. [容器化部署流程](#容器化部署流程)
5. [性能优化与安全加固](#性能优化与安全加固)

## Dockerfile详解

**Section sources**
- [Dockerfile](file://manifest/docker/Dockerfile#L1-L41)

### 基础镜像选择
Dockerfile采用多阶段构建策略，第一阶段使用`golang:1.24-alpine`作为构建镜像。选择Alpine Linux作为基础镜像的主要原因是其极小的体积（约5MB），这能显著减少最终镜像的大小，提高传输效率和安全性。

### 构建阶段分析
构建阶段（builder stage）主要完成以下操作：
1. 设置工作目录为`/build`
2. 复制项目源码到容器内
3. 设置Go模块代理为国内镜像源`https://goproxy.cn`
4. 执行`go mod tidy`整理依赖
5. 编译生成可执行文件，使用`-ldflags "-s -w"`参数去除调试信息，减小二进制文件大小

### 运行阶段分析
运行阶段（runtime stage）基于`alpine:latest`镜像，包含以下关键配置：
1. 设置工作目录为`/app`
2. 配置时区为`Asia/Shanghai`
3. 使用阿里云镜像源加速包管理
4. 安装必要的系统工具（curl、tzdata）
5. 复制构建阶段生成的可执行文件和资源配置文件
6. 配置健康检查机制，通过访问`/api/monitor/heathcheck`接口检测服务状态
7. 暴露服务端口12401

## 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)

### 生产环境配置
生产环境的`docker-compose.yml`文件定义了kami_backend服务的部署配置：
- 使用预构建的镜像，镜像名称包含分支和构建编号
- 设置容器名称和自动重启策略
- 将宿主机的127.0.0.1:22401端口映射到容器的12401端口
- 挂载日志和配置文件目录，实现数据持久化
- 连接到外部网络`1panel-network`

### 本地开发配置
`docker-compose-local.yaml`文件专为本地开发环境设计，具有以下特点：
- 使用`build`指令从本地Dockerfile构建镜像
- 设置构建参数`USE_PROXY=1`，启用代理配置
- 使用本地最新的镜像标签
- 简化的端口映射配置
- 相同的网络配置，确保与生产环境的一致性

### 配置差异对比
两种配置文件的主要差异体现在：
1. **镜像来源**：生产环境使用预构建镜像，本地环境使用本地构建
2. **版本控制**：生产环境包含详细的版本信息，本地环境使用latest标签
3. **构建参数**：本地环境支持代理参数传递
4. **容器命名**：生产环境包含版本信息，本地环境使用固定名称

## 部署脚本说明

**Section sources**
- [install.sh](file://manifest/docker/install.sh#L1-L144)
- [install-simple.sh](file://manifest/docker/install-simple.sh#L1-L131)
- [install-one.sh](file://manifest/docker/install-one.sh#L1-L134)
- [install-test.sh](file://manifest/docker/install-test.sh#L1-L133)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh#L1-L20)

### 主要部署脚本功能
项目提供了多个部署脚本以适应不同场景：

#### install.sh
完整部署脚本，执行流程包括：
1. 交互式选择要部署的应用
2. 克隆代码仓库
3. 停止并删除现有容器
4. 停止所有其他Docker容器
5. 构建并启动新容器
6. 重启所有kami_前缀的容器
7. 清理临时文件和悬空镜像
8. 自我删除脚本文件

#### install-simple.sh
简化版部署脚本，主要差异：
1. 仅在部署网关服务时停止其他容器
2. 不重启所有kami_前缀的容器
3. 不自我删除，便于重复使用

#### install-one.sh
支持命令行参数的部署脚本，可通过`-c`参数指定要部署的应用编号，适合自动化部署场景。

#### install-test.sh
测试环境专用部署脚本，使用测试环境的docker-compose配置文件。

### 辅助脚本
`wait-for-it.sh`脚本用于在服务启动前等待依赖服务（如数据库）就绪，确保服务启动顺序的正确性。

## 容器化部署流程

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

### 镜像构建
1. 进入项目根目录
2. 执行`docker build -f manifest/docker/Dockerfile -t kami_backend:latest .`
3. 构建过程将自动完成依赖下载、代码编译和镜像打包

### 服务启动
本地开发环境启动：
```bash
docker compose -f manifest/docker/docker-compose-local.yaml up -d
```

生产环境启动：
```bash
docker compose -f manifest/docker/docker-compose.yml up -d
```

### 日志查看
查看容器日志：
```bash
docker logs kami_backend
```

实时查看日志：
```bash
docker logs -f kami_backend
```

### 容器管理
常用管理命令：
- 查看容器状态：`docker ps`
- 停止容器：`docker stop kami_backend`
- 启动容器：`docker start kami_backend`
- 删除容器：`docker rm kami_backend`
- 进入容器：`docker exec -it kami_backend /bin/sh`

## 性能优化与安全加固

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

### 性能优化措施
1. **多阶段构建**：分离构建环境和运行环境，显著减小最终镜像体积
2. **二进制优化**：编译时使用`-s -w`参数去除调试符号，减小二进制文件大小
3. **Alpine基础镜像**：使用轻量级Linux发行版，减少攻击面和资源占用
4. **健康检查**：配置定期健康检查，及时发现和恢复异常服务

### 安全加固措施
1. **国内镜像源**：使用阿里云和goproxy.cn镜像源，避免从不可信源下载依赖
2. **最小化安装**：仅安装必要的系统包，减少潜在安全漏洞
3. **非root用户运行**：建议在生产环境中配置容器以非root用户运行
4. **网络隔离**：使用外部网络`1panel-network`，实现服务间的网络隔离
5. **环境变量管理**：敏感配置通过环境变量传递，避免硬编码在代码中

### 最佳实践建议
1. **镜像版本控制**：生产环境使用具体的版本标签，避免使用latest标签
2. **资源限制**：在docker-compose中配置内存和CPU限制，防止单个容器耗尽系统资源
3. **日志轮转**：配置日志轮转策略，防止日志文件无限增长
4. **定期更新**：定期更新基础镜像和依赖包，及时修复已知安全漏洞
5. **安全扫描**：在CI/CD流程中集成容器镜像安全扫描工具