# OPENCLAW AKS 部署 HTTPS 配置指南

## 概述

本指南说明如何为 OPENCLAW 平台 agent 在 AKS 上配置 HTTPS 访问，使用自签名证书解决只有 DNS 域名但没有正式证书的问题。

## 前置条件

1. 已部署 OPENCLAW 到 AKS
2. 已安装 nginx-ingress-controller
3. 有域名指向 AKS Ingress IP
4. 已安装 `kubectl` 和 `openssl`

## 解决方案：使用自签名证书

### 步骤 1: 生成自签名证书

使用提供的脚本生成自签名证书：

```bash
# 给脚本添加执行权限
chmod +x generate-self-signed-cert.sh

# 运行脚本生成证书（替换为你的实际域名）
./generate-self-signed-cert.sh openclaw.yourdomain.com openclaw openclaw-tls
```

**参数说明：**
- 第一个参数：你的域名（例如：`openclaw.example.com`）
- 第二个参数：Kubernetes 命名空间（默认：`openclaw`）
- 第三个参数：Kubernetes Secret 名称（默认：`openclaw-tls`）

### 步骤 2: 更新部署配置

确保 `deploay.yaml` 中的 Ingress 配置已包含 TLS 部分（已更新）：

```yaml
spec:
  tls:
  - hosts:
    - openclaw.yourdomain.com  # 你的域名
    secretName: openclaw-tls   # Secret 名称
  rules:
  - host: openclaw.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: openclaw
            port:
              number: 18789
```

### 步骤 3: 应用配置

```bash
# 应用更新后的配置
kubectl apply -f deploay.yaml

# 验证 Ingress 配置
kubectl get ingress -n openclaw

# 查看证书 Secret
kubectl get secret openclaw-tls -n openclaw
```

### 步骤 4: 配置 DNS

确保你的域名指向 AKS Ingress 的外部 IP：

```bash
# 获取 Ingress IP
kubectl get ingress -n openclaw

# 在 DNS 提供商处添加 A 记录：
# openclaw.yourdomain.com -> <INGRESS_IP>
```

### 步骤 5: 访问测试

1. 在浏览器中访问：`https://openclaw.yourdomain.com`
2. 浏览器会显示安全警告（这是正常的，因为使用的是自签名证书）
3. 点击"高级" -> "继续访问"（Chrome）或"接受风险并继续"（Firefox）
4. 之后即可正常访问 OPENCLAW UI

## 手动生成证书（可选）

如果脚本无法使用，可以手动生成：

```bash
# 1. 生成私钥
openssl genrsa -out tls.key 2048

# 2. 生成证书签名请求
openssl req -new -key tls.key -out tls.csr \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=OpenClaw/CN=openclaw.yourdomain.com"

# 3. 生成自签名证书（包含 SAN）
openssl x509 -req -days 365 -in tls.csr -signkey tls.key \
  -out tls.crt \
  -extensions v3_req \
  -extfile <(cat <<EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req

[v3_req]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = openclaw.yourdomain.com
DNS.2 = *.openclaw.yourdomain.com
DNS.3 = localhost
IP.1 = 127.0.0.1
EOF
)

# 4. 创建 Kubernetes Secret
kubectl create secret tls openclaw-tls \
  --cert=tls.crt \
  --key=tls.key \
  --namespace=openclaw
```

## 注意事项

### 自签名证书的限制

1. **浏览器警告**：所有浏览器都会显示安全警告，需要用户手动接受
2. **有效期**：默认证书有效期为 365 天，到期后需要重新生成
3. **不适用于生产环境**：自签名证书不适合生产环境，仅用于开发/测试

### 生产环境建议

对于生产环境，建议使用：

1. **Let's Encrypt**（免费，自动续期）
   ```bash
   # 安装 cert-manager
   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
   
   # 配置 ClusterIssuer
   # 然后 Ingress 添加注解：
   # cert-manager.io/cluster-issuer: letsencrypt-prod
   ```

2. **Azure Key Vault**（Azure 托管证书）

3. **购买商业证书**

### 更新证书

证书到期后，重新生成并更新：

```bash
# 重新生成证书
./generate-self-signed-cert.sh openclaw.yourdomain.com openclaw openclaw-tls

# 重启 Ingress Controller（如果需要）
kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller
```

## 故障排查

### 问题 1: 证书 Secret 不存在

```bash
# 检查 Secret
kubectl get secret openclaw-tls -n openclaw

# 如果不存在，重新创建
./generate-self-signed-cert.sh <your-domain> openclaw openclaw-tls
```

### 问题 2: Ingress 无法访问

```bash
# 检查 Ingress 状态
kubectl describe ingress openclaw -n openclaw

# 检查 Ingress Controller
kubectl get pods -n ingress-nginx

# 检查 Service
kubectl get svc openclaw -n openclaw
```

### 问题 3: HTTPS 连接失败

```bash
# 检查证书是否正确加载
kubectl get ingress openclaw -n openclaw -o yaml | grep -A 5 tls

# 检查 Ingress Controller 日志
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller
```

## 总结

使用自签名证书可以快速解决 OPENCLAW 在 AKS 上需要 HTTPS 访问的问题。虽然会有浏览器警告，但对于开发和测试环境已经足够。生产环境建议使用 Let's Encrypt 或商业证书。