部署指南 — LingFlow 文档

本地部署

本地部署适用于开发与调试场景，直接通过 Go 工具链编译源码生成二进制后运行。

bash

go build -o lingflow main.go
./lingflow

Docker 部署

通过容器化部署可实现环境隔离与一致交付，建议使用 --env-file 注入环境变量以避免敏感信息写入镜像。

bash

docker build -t lingflow .
docker run -p 4030:4030 --env-file .env lingflow

Kubernetes 部署

项目提供了完整的 Kubernetes 部署配置文件，位于 k8s/ 目录。

配置文件结构

text

k8s/
├── deployment.yaml    # 应用部署配置（3副本、滚动更新、健康检查）
├── service.yaml       # ClusterIP 服务暴露
├── ingress.yaml       # Nginx Ingress 网关（支持 WebSocket + TLS）
├── configmap.yaml     # 非敏感环境变量配置
└── secret.yaml        # 敏感配置项（需手动填写 base64 编码值）

部署步骤

按照以下顺序依次应用配置文件，确保依赖资源（ConfigMap、Secret）先于工作负载创建。

bash

# 1. 创建命名空间（可选）
kubectl create namespace lingflow

# 2. 创建 ConfigMap
kubectl apply -f k8s/configmap.yaml

# 3. 创建 Secret（需先填写敏感值）
kubectl apply -f k8s/secret.yaml

# 4. 创建 Service
kubectl apply -f k8s/service.yaml

# 5. 创建 Deployment
kubectl apply -f k8s/deployment.yaml

# 6. 创建 Ingress（可选）
kubectl apply -f k8s/ingress.yaml

ConfigMap 配置说明

ConfigMap 用于存储非敏感的环境变量，所有 Pod 共享同一份配置。

配置项	说明
AWS_REGION	S3 所在区域
AWS_BEDROCK_REGION	Bedrock 服务区域
AWS_BEDROCK_MODEL_ID	模型标识符
SKILLS_S3_BUCKET	技能存储桶名称
WSS_HEARTBEAT_INTERVAL	心跳间隔
IS_ALLOW_USER_CREATE_SKILL	是否允许技能创建
ENABLE_BEDROCK_GUARDRAIL	是否启用 Guardrail

Secret 配置

敏感配置需要 base64 编码后填入 k8s/secret.yaml，切勿以明文形式提交到版本控制。

bash

# 生成 base64 编码值
echo -n "your-access-key" | base64
echo -n "your-secret-key" | base64
echo -n "your-auth-secret" | base64
echo -n "your-api-key" | base64

健康检查

部署配置包含 liveness 和 readiness 探针，kubelet 会周期性探测以决定流量转发与实例重启。

yaml

livenessProbe:
  httpGet:
    path: /health
    port: 4030
  initialDelaySeconds: 10
  periodSeconds: 30
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /ready
    port: 4030
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

资源限制

通过 requests 与 limits 限制单个 Pod 的资源用量，避免单实例异常耗尽节点资源。

yaml

resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

安全上下文

通过 Pod Security Context 收紧容器权限，遵循最小权限原则。

yaml

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop:
      - ALL

水平扩展

可通过手动修改副本数或启用 HPA（Horizontal Pod Autoscaler）基于 CPU 利用率自动扩缩容。

bash

# 修改副本数
kubectl scale deployment lingflow --replicas=5

# 或使用 HPA 自动扩缩容
kubectl autoscale deployment lingflow --min=3 --max=10 --cpu-percent=70

滚动更新

配置已启用 RollingUpdate 策略，maxSurge=1, maxUnavailable=0，确保零停机更新。

bash

# 更新镜像触发滚动更新
kubectl set image deployment/lingflow lingflow=lingflow:v2.0.0

# 查看滚动更新状态
kubectl rollout status deployment/lingflow

# 回滚到上一个版本
kubectl rollout undo deployment/lingflow

Ingress 配置（WebSocket 支持）

Nginx Ingress 需要特殊配置以支持 WebSocket 长连接，需延长代理超时并指定后端 Service。

yaml

annotations:
  nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
  nginx.ingress.kubernetes.io/websocket-services: "lingflow-service"
  nginx.ingress.kubernetes.io/ssl-redirect: "true"
  cert-manager.io/cluster-issuer: "letsencrypt-prod"

AWS Lambda + API Gateway 部署

参考 internal/services/aws/lambda.go 实现 Serverless 部署。适用于低频调用场景，按需付费。

零运维成本，无需管理服务器
自动弹性伸缩
API Gateway WebSocket 集成
按调用次数计费

AWS 基础设施准备

创建 S3 存储桶

LingFlow 将技能文件以 Markdown 形式持久化到 S3，需提前创建存储桶并选择与 Bedrock 接近的区域。

bash

aws s3api create-bucket \
  --bucket skill-bucket-bedrock \
  --region ap-southeast-5 \
  --create-bucket-configuration LocationConstraint=ap-southeast-5

创建 IAM 用户和策略

需要为 LingFlow 创建具有 S3 和 Bedrock 权限的 IAM 用户，遵循最小权限原则，仅授予必要的操作。

S3 权限策略：

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:HeadObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::skill-bucket-bedrock",
        "arn:aws:s3:::skill-bucket-bedrock/*"
      ]
    }
  ]
}

S3 权限说明：

Action	用途	对应代码
s3:ListBucket	列出存储桶中的技能文件	LoadAllSkills
s3:GetObject	下载技能 Markdown 内容	LoadSkill
s3:HeadObject	检查技能是否已存在	SkillExists
s3:PutObject	上传新技能或占位文件	UploadSkill
s3:DeleteObject	删除技能文件（创建失败时清理）	DeleteSkill

Bedrock 权限策略：

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:Converse",
        "bedrock:ConverseStream"
      ],
      "Resource": "*"
    }
  ]
}

注意：Resource 需要两条记录 - 存储桶本身（用于 ListBucket）和存储桶内对象（用于对象级操作）。

验证 AWS 配置

完成 IAM 配置后，建议先通过 AWS CLI 验证 S3 与 Bedrock 访问权限是否生效，再启动服务。

bash

# 验证 S3 访问
aws s3 ls s3://skill-bucket-bedrock/skills/

# 验证 Bedrock 访问
aws bedrock list-foundation-models --region us-east-1