macroadster/starlight-helm
GitHub: macroadster/starlight-helm
一套用于在 Kubernetes 上快速部署 Starlight Bitcoin 智能合约平台的 Helm Chart，包含 API 服务、Stargate 后端和数据库。
Stars: 1 | Forks: 0
# Starlight Helm Stack
一个完整的 Bitcoin 原生智能合约系统，在保持区块链安全的同时实现有用的工作。该技术栈结合了由 AI 驱动的安全机制（可检测区块链图像中的隐藏数据）以及用于提案、资金和验证工作的完整工作流系统——所有这些都建立在 Bitcoin 之上，支持智能合约、escrow 和争议解决。
用于运行 Starlight API、Stargate 和 Postgres 的最小 chart。
## 快速开始
```
# 1. 创建 secrets（身份验证必需）
kubectl create secret generic stargate-stack-secrets \
--from-literal=starlight-api-key="starlight-api-$(date +%s)-$(openssl rand -hex 8)" \
--from-literal=starlight-ingest-token="starlight-ingest-$(date +%s)-$(openssl rand -hex 8)" \
--from-literal=stargate-api-key="starlight-api-$(date +%s)-$(openssl rand -hex 8)" \
--from-literal=stargate-ingest-token="stargate-ingest-$(date +%s)-$(openssl rand -hex 8)" \
--from-literal=starlight-stego-callback-secret="stego-callback-$(date +%s)-$(openssl rand -hex 8)"
# 2. 使用 secrets 部署
helm install starlight-stack . \
--set secrets.createDefault=false \
--set secrets.name=stargate-stack-secrets \
--set secrets.starlightApiKey=true \
--set secrets.starlightIngestToken=true \
--set secrets.stargateApiKey=true \
--set secrets.stargateIngestToken=true \
--set secrets.starlightStegoCallbackSecret=true
# 3. 验证部署
kubectl get pods
kubectl port-forward svc/starlight-api 8080:8080 &
curl http://localhost:8080/health
```
**⚠️ 关键的 Token 匹配要求**：
- `starlight-api-key` 和 `stargate-api-key` **必须匹配**，Stargate → Starlight API 调用才能正常工作
- `starlight-ingest-token` 和 `stargate-ingest-token` **必须匹配**，Starlight → Stargate 回调才能正常工作
- Token 不匹配会导致 403/401 错误并阻碍 inscription 工作流
## 要求
- 具有 Docker/Helm/Kubectl 对集群的访问权限（支持 kind/minikube）。
- 镜像在本地或 registry 中可用：
- `stargate:latest`（由 `stargate/Dockerfile` 构建）
- `starlight-api:latest`（由 `starlight/Dockerfile` 构建）
## Values
## 构建镜像（本地）
```
# Stargate
cd stargate
docker build -t stargate:latest .
# Starlight API（如果不可用）
cd starlight
docker build -t starlight-api:latest .
```
## Secret 设置（生产环境必需）
Starlight ↔ Stargate 集成需要身份验证 token 以进行安全通信。请在部署前创建 secret：
### 选项 1：自动创建 Secret（推荐）
```
cd starlight-helm
# 使用安全的随机值创建 secrets
# 注意：对于 Stargate → Starlight 调用，starlight-api-key 和 stargate-api-key 必须匹配
# 注意：对于 Starlight → Stargate 回调，starlight-ingest-token 和 stargate-ingest-token 必须匹配
TIMESTAMP=$(date +%s)
RANDOM=$(openssl rand -hex 8)
kubectl create secret generic stargate-stack-secrets \
--from-literal=starlight-api-key="starlight-api-$TIMESTAMP-$RANDOM" \
--from-literal=starlight-ingest-token="starlight-ingest-$TIMESTAMP-$RANDOM" \
--from-literal=stargate-api-key="starlight-api-$TIMESTAMP-$RANDOM" \
--from-literal=stargate-ingest-token="starlight-ingest-$TIMESTAMP-$RANDOM" \
--from-literal=starlight-stego-callback-secret="stego-callback-$TIMESTAMP-$(openssl rand -hex 8)"
# 在 Helm 中启用 secret 使用
helm install starlight-stack . \
--set secrets.createDefault=false \
--set secrets.name=stargate-stack-secrets \
--set secrets.starlightApiKey=true \
--set secrets.starlightIngestToken=true \
--set secrets.stargateApiKey=true \
--set secrets.stargateIngestToken=true \
--set secrets.starlightStegoCallbackSecret=true
```
### 选项 2：手动创建 Secret
```
# 使用您自己的值创建 secret
# 重要提示：API keys 和 ingest tokens 请使用匹配的值
kubectl create secret generic stargate-stack-secrets \
--from-literal=starlight-api-key="your-shared-api-key" \
--from-literal=starlight-ingest-token="your-shared-ingest-token" \
--from-literal=stargate-api-key="your-shared-api-key" \
--from-literal=stargate-ingest-token="your-shared-ingest-token" \
--from-literal=starlight-stego-callback-secret="your-stego-callback-secret"
# 启用 secret 使用进行部署
helm install starlight-stack . \
--set secrets.createDefault=false \
--set secrets.name=stargate-stack-secrets \
--set secrets.starlightApiKey=true \
--set secrets.starlightIngestToken=true \
--set secrets.stargateApiKey=true \
--set secrets.stargateIngestToken=true \
--set secrets.starlightStegoCallbackSecret=true
```
### Secret 密钥说明
| Secret Key | 使用者 | 用途 |
|------------|----------|---------|
| `starlight-api-key` | Starlight API | 对 `/inscribe` 和受保护的 endpoint 进行身份验证 |
| `starlight-ingest-token` | Starlight API | 用于 Stargate ingestion 回调的 token |
| `stargate-api-key` | Stargate | 用于调用 Starlight 服务的 API key |
| `stargate-ingest-token` | Stargate | 用于 Stargate ingestion endpoint 的 token |
| `starlight-stego-callback-secret` | Starlight API | 用于隐写术检测回调的 HMAC secret |
**重要**：
- `starlight-api-key` 和 `stargate-api-key` **必须匹配**，Stargate → Starlight API 调用才能正常工作。
- `starlight-ingest-token` 和 `stargate-ingest-token` **必须匹配**，Starlight → Stargate 回调才能正常工作。
### 选项 3：开发环境（无身份验证）
```
# 仅用于开发 - 禁用身份验证
helm install starlight-stack . \
--set starlight.allowAnonymousScan=true \
--set starlight.apiKey="demo-api-key" \
--set stargate.apiKey="demo-api-key"
```
## 安装
```
cd starlight-helm
# 基本安装（不包含 secrets - 不推荐用于生产环境）
helm install starlight-stack . \
--set image.stargate.repository=stargate \
--set image.stargate.tag=latest \
--set image.starlight.repository=starlight-api \
--set image.starlight.tag=latest
# 带有 secrets 的生产环境安装（推荐）
helm install starlight-stack . \
--set secrets.createDefault=false \
--set secrets.name=stargate-stack-secrets \
--set secrets.starlightApiKey=true \
--set secrets.starlightIngestToken=true \
--set secrets.stargateApiKey=true \
--set secrets.stargateIngestToken=true \
--set secrets.starlightStegoCallbackSecret=true
# 用于 testnet 部署
helm install starlight-stack . \
--set stargate.bitcoinNetwork=testnet \
--set secrets.createDefault=false \
--set secrets.name=stargate-stack-secrets \
--set secrets.starlightApiKey=true \
--set secrets.starlightIngestToken=true \
--set secrets.stargateApiKey=true \
--set secrets.stargateIngestToken=true \
--set secrets.starlightStegoCallbackSecret=true
# 默认值已指向上述标签；仅在使用不同名称时覆盖。
# 启用 ingress（示例；为您的集群更新 hosts/tls）
helm upgrade --install starlight-stack . \
--set ingress.enabled=true \
--set ingress.className=nginx
# 对于本地 ingress 测试（带有 ingress-nginx 的 docker-desktop/minikube），请添加到 /etc/hosts：
# 127.0.0.1 starlight.local stargate.local
# TLS：默认值期望一个带有 SANs starlight.local、stargate.local 的 secret `stargate-stack-tls`，
# kubectl create secret tls stargate-stack-tls --cert=stargate-stack.crt --key=stargate-stack.key
# 然后访问：
# curl -kI https://starlight.local/
# curl -kI https://stargate.local/
# 可观测性
# - 后端 metrics：https://stargate.local/metrics（prometheus 格式）
# - Starlight metrics：如果已代理则为 https://stargate.local/metrics，或在端口 8080 上进行 service scrape（/metrics）
# - 包含用于 Prometheus 自动抓取的 service annotations（prometheus.io/scrape=true）
```
## 验证
```
# 检查 pod 状态
kubectl get pods
# 检查 services
kubectl get svc stargate starlight-api stargate-postgres
# 用于测试的 port forward
kubectl port-forward svc/stargate 3001:3001 &
kubectl port-forward svc/starlight-api 8080:8080 &
# 测试健康检查端点
curl http://localhost:3001/api/health
curl http://localhost:8080/health
# 测试 Starlight inscription（需要身份验证）
# 从 secret 中获取 API key：
STARLIGHT_API_KEY=$(kubectl get secret stargate-stack-secrets -o jsonpath='{.data.starlight-api-key}' | base64 -d)
curl -X POST "http://localhost:8080/inscribe" \
-H "Authorization: Bearer $STARLIGHT_API_KEY" \
-F "image=@test-image.png" \
-F "message=test message" \
-F "method=lsb"
```
## Mock 合约和 Ingestion 的 CI 自动化
对于需要模拟合约和提案 ingestion 的持续集成 (CI) 环境或本地开发，您可以使用以下设置：
### Mock 合约和任务
要在启动时自动将一组演示合约和任务加载到系统中，请在您的 `values.yaml` 中配置以下内容：
- \`stargate.seedFixtures\`：将其设置为 \`true\`。启用后，Stargate 后端在初始化时将检查 \`mcp_contracts\` 和 \`mcp_tasks\` 数据库表是否为空。如果为空，它将使用预定义的演示数据填充它们。
\`\`\`yaml
stargate:
seedFixtures: true # 设置为 true 以加载演示合约和任务
\`\`\`
演示数据定义在 Stargate 源代码的 \`stargate/backend/mcp/fixtures.go\` 中。如果您的测试需要自定义 mock 数据，通常需要修改此源文件或实现一种覆盖它的机制。
### 提案的 Mock Ingestion
系统通过轮询 \`starlight_ingestions\` 服务中的 "pending" 记录来 ingest 提案。虽然没有类似于 \`seedFixtures\` 的直接 ingestion "mocking" 标志，但您可以通过以下方式在 CI 环境中模拟提案 ingestion：
1. **创建 Pending Ingestion 记录**：在您的 CI 设置中，您将以编程方式将状态为 "pending" 的记录插入到 \`starlight_ingestions\` 服务/数据库中。这些记录代表您想要被 ingest 的提案。
2. **使用 Markdown 提案**：ingestion 同步服务可以从 Markdown 字符串中解析提案。您可以制作特定的 Markdown 内容（可能嵌入在 ingestion 记录元数据中）来定义您的 mock 提案。
3. **控制默认值**：您可以使用环境变量来影响已 ingest 提案的默认预算和资金地址：
- \`STARGATE_DEFAULT_BUDGET_SATS\`：设置此环境变量可为未指定预算的提案定义一个默认预算（以 satoshis 为单位）。
- \`STARGATE_DEFAULT_FUNDING_ADDRESS\`：设置此环境变量可为提案定义一个默认资金地址。
这些环境变量可以直接在您的部署配置中（例如在 \`Deployment\` manifest 中，或通过 Helm 的 \`--set\` 标志）为 Stargate 后端进行设置。
这些设置提供了一种可靠的方法，使您能够以自动化方式使用预定义的合约和提案来测试 Starlight 集群的行为。
## 故障排除
### 403/401 身份验证错误
#### Starlight API 返回 403 Forbidden
**原因**：Stargate 和 Starlight 之间的 API key 不匹配
```
# 检查 API key 不匹配
echo "Starlight expects:"
kubectl exec deployment/starlight-api -- env | grep STARGATE_API_KEY
echo "Stargate sends:"
kubectl exec deployment/stargate -- env | grep STARGATE_API_KEY
# 通过更新 Stargate API key 使其与 Starlight 匹配来修复
kubectl patch secret stargate-stack-secrets --patch='{"data":{"stargate-api-key":"'$(kubectl get secret stargate-stack-secrets -o jsonpath='{.data.starlight-api-key}')'"}}'
kubectl rollout restart deployment/stargate
```
#### Stargate 回调返回 401 Unauthorized
**原因**：Starlight 和 Stargate 之间的 Ingest token 不匹配
```
# 检查 ingest token 不匹配
echo "Starlight sends:"
kubectl exec deployment/starlight-api -- env | grep STARGATE_INGEST_TOKEN
echo "Stargate expects:"
kubectl exec deployment/stargate -- env | grep STARGATE_INGEST_TOKEN
# 通过更新 Stargate ingest token 使其与 Starlight 匹配来修复
STARLIGHT_INGEST_TOKEN=$(kubectl get secret stargate-stack-secrets -o jsonpath='{.data.starlight-ingest-token}' | base64 -d)
kubectl patch secret stargate-stack-secrets --patch='{"data":{"stargate-ingest-token":"'$(echo -n "$STARLIGHT_INGEST_TOKEN" | base64)'"}}'
kubectl rollout restart deployment/stargate
```
### 403 Forbidden 错误
如果您从 Starlight 的 `/inscribe` endpoint 收到 `403 Forbidden`：
```
# 检查 API key 不匹配
echo "Starlight expects:"
kubectl exec deployment/starlight-api -- env | grep STARGATE_API_KEY
echo "Stargate sends:"
kubectl exec deployment/stargate -- env | grep STARGATE_API_KEY
# 通过更新 Stargate API key 使其与 Starlight 匹配来修复
kubectl patch secret stargate-stack-secrets --patch='{"data":{"stargate-api-key":"'$(kubectl get secret stargate-stack-secrets -o jsonpath='{.data.starlight-api-key}')'"}}'
kubectl rollout restart deployment/stargate
```
### 回调问题
如果 Starlight → Stargate 回调失败：
```
# 检查 callback URLs 和 tokens
echo "Starlight sends:"
kubectl exec deployment/starlight-api -- env | grep STARGATE_INGEST_TOKEN
echo "Stargate expects:"
kubectl exec deployment/stargate -- env | grep STARGATE_INGEST_TOKEN
# 通过更新 Stargate 使其与 Starlight 匹配来修复 token 不匹配
STARLIGHT_INGEST_TOKEN=$(kubectl get secret stargate-stack-secrets -o jsonpath='{.data.starlight-ingest-token}' | base64 -d)
kubectl patch secret stargate-stack-secrets --patch='{"data":{"stargate-ingest-token":"'$(echo -n "$STARLIGHT_INGEST_TOKEN" | base64)'"}}'
kubectl rollout restart deployment/stargate
# 手动测试 callback 端点
STARGATE_INGEST_TOKEN=$(kubectl get secret stargate-stack-secrets -o jsonpath='{.data.stargate-ingest-token}' | base64 -d)
curl -X POST "http://localhost:3001/api/ingest-inscription" \
-H "X-Ingest-Token: $STARGATE_INGEST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"test","filename":"test.png","method":"lsb","message_length":10,"image_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/Ptq4YQAAAABJRU5ErkJggg==","metadata":{}}'
```
## Secret 管理
### 查看当前 Secret
```
# 列出所有 secret 值（已解码）
kubectl get secret stargate-stack-secrets -o yaml | awk '
/^\s*[a-zA-Z-]+:/ {
key = $1
gsub(/:/, "", key)
getline
if (/data:/) {
getline
value = $2
cmd = "echo " value " | base64 -d"
cmd | getline decoded
close(cmd)
print key ": " decoded
}
}'
# 或查看特定 secret
kubectl get secret stargate-stack-secrets -o jsonpath='{.data.starlight-api-key}' | base64 -d
```
### 更新 Secret
```
# 更新单个 secret 值
kubectl patch secret stargate-stack-secrets --patch='{"data":{"starlight-api-key":"'$(echo -n 'new-api-key' | base64)'"}}'
# 重要提示：更新匹配对以维持通信
kubectl patch secret stargate-stack-secrets --patch='{"data":{"stargate-api-key":"'$(echo -n 'new-api-key' | base64)'"}}'
# 重启 deployments 以加载新 secrets
kubectl rollout restart deployment/starlight-api
kubectl rollout restart deployment/stargate
```
### 轮换 Secret
```
# 生成新 secrets 并更新（带有匹配对）
TIMESTAMP=$(date +%s)
RANDOM=$(openssl rand -hex 8)
kubectl create secret generic stargate-stack-secrets-new \
--from-literal=starlight-api-key="starlight-api-$TIMESTAMP-$RANDOM" \
--from-literal=starlight-ingest-token="starlight-ingest-$TIMESTAMP-$RANDOM" \
--from-literal=stargate-api-key="starlight-api-$TIMESTAMP-$RANDOM" \
--from-literal=stargate-ingest-token="starlight-ingest-$TIMESTAMP-$RANDOM" \
--from-literal=starlight-stego-callback-secret="stego-callback-$TIMESTAMP-$(openssl rand -hex 8)"
# 替换旧 secret
kubectl delete secret stargate-stack-secrets
kubectl get secret stargate-stack-secrets-new -o yaml | sed 's/name: stargate-stack-secrets-new/name: stargate-stack-secrets/' | kubectl apply -f -
kubectl delete secret stargate-stack-secrets-new
# 重启 deployments
kubectl rollout restart deployment/starlight-api
kubectl rollout restart deployment/stargate
```
## 卸载
```
helm uninstall starlight-stack
kubectl delete secret stargate-stack-secrets # Optional: remove secrets
```
标签：子域名突变, 测试用例, 请求拦截