open-im-server-deploy/.gitea/SECRETS_CONFIG.md

# OpenIM Server 项目 Gitea Actions 秘钥配置指南

## 📋 概述

本指南说明如何在 Gitea 中配置必要的秘钥，以支持 OpenIM Server 项目的自动构建和部署到阿里云 ACK。

## 🔑 必需秘钥配置

### 1. Docker Hub 相关秘钥

#### DOCKER_USERNAME
- **描述**: Docker Hub 用户名
- **示例**: `openim`
- **获取方式**: 在 Docker Hub 注册账号

#### DOCKER_PASSWORD
- **描述**: Docker Hub 密码或访问令牌
- **示例**: `your-docker-password` 或 `dckr_pat_xxxxxxxxxxxx`
- **推荐**: 使用访问令牌（Access Token）而不是密码
- **获取方式**: 
  1. 登录 Docker Hub
  2. 进入 Account Settings → Security
  3. 创建 New Access Token

### 2. 阿里云 ACK 相关秘钥

#### KUBECONFIG
- **描述**: 阿里云 ACK 集群的 kubeconfig 内容（base64编码）
- **格式**: base64编码的YAML格式kubeconfig文件内容
- **获取方式**: 见下方详细说明

#### ALIBABA_CLOUD_ACCESS_KEY_ID (可选)
- **描述**: 阿里云AccessKey ID
- **用途**: 用于通过aliyun CLI获取kubeconfig
- **获取方式**: 阿里云控制台 → 访问控制 → AccessKey管理

#### ALIBABA_CLOUD_ACCESS_KEY_SECRET (可选)
- **描述**: 阿里云AccessKey Secret
- **用途**: 用于通过aliyun CLI获取kubeconfig
- **获取方式**: 阿里云控制台 → 访问控制 → AccessKey管理

#### ACK_CLUSTER_ID (可选)
- **描述**: 阿里云ACK集群ID
- **用途**: 用于通过aliyun CLI获取kubeconfig
- **获取方式**: ACK控制台集群详情页

#### ACK_REGION (可选)
- **描述**: 阿里云ACK集群区域
- **默认值**: `cn-hangzhou`
- **示例**: `cn-beijing`, `cn-shanghai`, `cn-shenzhen`

#### NAMESPACE (可选)
- **描述**: Kubernetes命名空间
- **默认值**: `openim`
- **示例**: `openim`, `default`, `production`

## 🚀 获取阿里云 ACK KUBECONFIG

### 方法1: 通过阿里云控制台（推荐）

1. **登录阿里云控制台**
   - 访问 [阿里云容器服务控制台](https://cs.console.aliyun.com/)

2. **选择集群**
   - 进入目标 ACK 集群详情页

3. **获取连接信息**
   - 点击 "连接信息" 标签
   - 复制 "公网访问" 或 "内网访问" 的 kubeconfig 内容

4. **编码kubeconfig**
   ```bash
   # 将获取的kubeconfig内容保存到文件
   cat > kubeconfig.yaml << 'EOF'
   apiVersion: v1
   clusters:
   - cluster:
       certificate-authority-data: LS0tLS1CRUdJTi...
       server: https://your-cluster-id.cn-hangzhou.cs.aliyuncs.com:6443
     name: kubernetes
   contexts:
   - context:
       cluster: kubernetes
       user: your-user
     name: kubernetes
   current-context: kubernetes
   kind: Config
   preferences: {}
   users:
   - name: your-user
     user:
       client-certificate-data: LS0tLS1CRUdJTi...
       client-key-data: LS0tLS1CRUdJTi...
   EOF
   
   # 编码为base64
   base64 -w 0 kubeconfig.yaml
   ```

### 方法2: 通过阿里云 CLI

1. **安装阿里云 CLI**
   ```bash
   # macOS
   brew install aliyun-cli
   
   # Linux
   curl -sSL https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz | tar -xzC /usr/local/bin
   ```

2. **配置认证**
   ```bash
   aliyun configure
   # 输入 AccessKey ID 和 AccessKey Secret
   ```

3. **获取kubeconfig并编码**
   ```bash
   # 获取指定集群的kubeconfig
   aliyun cs GET /k8s/clusters/{cluster_id}/user_config > kubeconfig.yaml
   
   # 编码为base64
   base64 -w 0 kubeconfig.yaml
   ```

## 🔧 在 Gitea 中配置秘钥

### 1. 进入仓库设置

1. 打开 OpenIM Server 项目仓库
2. 点击 "Settings" 标签
3. 在左侧菜单中点击 "Secrets"

### 2. 添加秘钥

点击 "New Secret" 按钮，依次添加以下秘钥：

#### 必需秘钥

##### DOCKER_USERNAME
- **Name**: `DOCKER_USERNAME`
- **Value**: 你的 Docker Hub 用户名

##### DOCKER_PASSWORD
- **Name**: `DOCKER_PASSWORD`
- **Value**: 你的 Docker Hub 密码或访问令牌

##### KUBECONFIG
- **Name**: `KUBECONFIG`
- **Value**: base64编码的kubeconfig文件内容

#### 可选秘钥

##### ALIBABA_CLOUD_ACCESS_KEY_ID
- **Name**: `ALIBABA_CLOUD_ACCESS_KEY_ID`
- **Value**: 阿里云AccessKey ID

##### ALIBABA_CLOUD_ACCESS_KEY_SECRET
- **Name**: `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- **Value**: 阿里云AccessKey Secret

##### ACK_CLUSTER_ID
- **Name**: `ACK_CLUSTER_ID`
- **Value**: ACK集群ID

##### ACK_REGION
- **Name**: `ACK_REGION`
- **Value**: ACK集群区域（默认：cn-hangzhou）

##### NAMESPACE
- **Name**: `NAMESPACE`
- **Value**: Kubernetes命名空间（默认：openim）

## 🚨 安全注意事项

### 1. 秘钥安全
- **不要** 将秘钥提交到代码仓库
- **定期轮换** 访问令牌和密码
- **使用最小权限** 原则配置访问权限

### 2. KUBECONFIG 安全
- **限制权限**: 确保kubeconfig只有必要的权限
- **定期更新**: 定期更新证书和密钥
- **监控访问**: 监控集群访问日志

### 3. Docker Hub 安全
- **使用访问令牌**: 优先使用访问令牌而不是密码
- **限制权限**: 只授予必要的仓库推送权限
- **定期轮换**: 定期更新访问令牌

## 🔍 故障排除

### 常见问题

#### 1. Docker 登录失败
```
Error: Cannot perform an interactive login from a non TTY device
```
**解决方案**: 检查 `DOCKER_USERNAME` 和 `DOCKER_PASSWORD` 是否正确配置

#### 2. kubectl 连接失败
```
Unable to connect to the server: x509: certificate signed by unknown authority
```
**解决方案**: 检查 `KUBECONFIG` 中的证书数据是否正确

#### 3. 镜像拉取失败
```
Error: pull access denied for openim/openim-api
```
**解决方案**: 检查 Docker Hub 权限和镜像名称是否正确

#### 4. 部署超时
```
deployment "openim-api" exceeded its progress deadline
```
**解决方案**: 检查集群资源是否充足，Pod 是否正常启动

### 调试命令

```bash
# 检查秘钥是否正确设置
echo "Docker username: $DOCKER_USERNAME"
echo "Kubeconfig length: ${#KUBECONFIG}"

# 测试 Docker 登录
echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin

# 测试 kubectl 连接
echo "$KUBECONFIG" | base64 -d > ~/.kube/config
kubectl cluster-info
kubectl get nodes
```

## 📚 参考文档

- [Gitea Actions 文档](https://docs.gitea.io/en-us/actions/)
- [阿里云 ACK 文档](https://help.aliyun.com/product/85222.html)
- [Docker Hub 访问令牌](https://docs.docker.com/docker-hub/access-tokens/)
- [Kubernetes kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
- [OpenIM 官方文档](https://docs.openim.io/)

## 🆘 支持

如遇到问题，请检查：
1. 秘钥是否正确配置
2. 网络连接是否正常
3. 权限是否充足
4. 集群状态是否正常

更多帮助请参考：
- Gitea Actions 日志
- 阿里云 ACK 控制台
- Docker Hub 状态页面
- OpenIM 官方文档