如何用 openwork-ee Helm 图表在 AWS EKS 上部署 OpenWork 并接入 RDS MySQL【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork这篇文章解决的任务是在 AWS 上用 Helm 把 OpenWork EE 部署到 Amazon EKS并把数据库接入 Amazon RDS for MySQL。推荐的 AWS 路径是 EKS Auto Mode 加 KubernetesLoadBalancerService让 AWS 直接从图表生成两个公网 Network Load BalancerNLB一个给 Den Web、一个给 Den API不需要预先安装 ingress 控制器。完整的操作细节来自仓库内的 AWS EKS operator runbook 和 openwork-ee Helm 图表 READMEAWS 侧的要点清单见 Deploy on AWS。这个部署最终会产生Den API端口8788和 Den Web端口3005默认禁用的可选 OpenWork Gatewayinference.enabled一个 RDS MySQL 数据库一个单组织single-orgOpenWork 部署默认两个公网 AWS NLBweb 一个、API 一个AWS 负责 EKS 控制面、节点生命周期、VPC 网络、负载均衡器、RDS、DNS、TLS 证书、IAM 和安全组openwork-ee 图表负责 OpenWork 的 Deployment、Service、ConfigMap、Secret、健康探针和数据库迁移 Job。准备条件AWS CLI 已认证到目标账户。不要用 AWS root 账户跑生产安装使用 AWS SSO 或只有集群、VPC/负载均衡、RDS、DNS、证书所需权限的 IAM 角色。本地或 CloudShell 里有kubectl、helm、eksctlEKS Auto Mode 要求eksctl版本0.195.0或更新。有权限创建 EKS、EC2/VPC、IAM、Elastic Load Balancing、RDS、Secrets Manager、Route 53 和 ACM 资源。一个真实的管理员邮箱第一个 owner 账户以及你控制的域名例如openwork.example.com和api.openwork.example.com。如果从 AWS Console 的 CloudShell 开始先显式设置区域并确认认证即使 Console 区域选择器已经显示正确区域export AWS_REGIONus-east-1 aws sts get-caller-identity aws configure get regionCloudShell 不一定自带 Helm 和 eksctl。安装时使用仓库文档给出的固定版本并在安装二进制前用对应 release 公布的校验和核对归档文件HELM_VERSIONv3.18.4 HELM_ARCHIVEhelm-${HELM_VERSION}-linux-amd64.tar.gz curl -fsSL https://get.helm.sh/${HELM_ARCHIVE} -o /tmp/${HELM_ARCHIVE} printf %s %s\n \ f8180838c23d7c7d797b208861fecb591d9ce1690d8704ed1e4cb8e2add966c1 \ /tmp/${HELM_ARCHIVE} | sha256sum --check --strict tar -xzf /tmp/${HELM_ARCHIVE} -C /tmp sudo install -m 0755 /tmp/linux-amd64/helm /usr/local/bin/helm EKSCTL_VERSIONv0.195.0 EKSCTL_ARCHIVEeksctl_Linux_amd64.tar.gz curl -fsSL \ https://github.com/eksctl-io/eksctl/releases/download/${EKSCTL_VERSION}/${EKSCTL_ARCHIVE} \ -o /tmp/${EKSCTL_ARCHIVE} printf %s %s\n \ 1cc86fd94da2378687f4db7c537da3c7316f2dca1347a4223a2ed86ad94dd818 \ /tmp/${EKSCTL_ARCHIVE} | sha256sum --check --strict tar -xzf /tmp/${EKSCTL_ARCHIVE} -C /tmp sudo install -m 0755 /tmp/eksctl /usr/local/bin/eksctl helm version eksctl version kubectl version --client上面的校验和是 Helmv3.18.4和eksctlv0.195.0官方 Linux AMD64 值如果升级其中某个固定版本要同时替换成对应官方 release 公布的校验和不能只改版本号。创建 EKS Auto Mode 集群export AWS_REGIONus-east-1 export CLUSTER_NAMEopenwork-ee eksctl create cluster \ --name $CLUSTER_NAME \ --region $AWS_REGION \ --enable-auto-mode aws eks update-kubeconfig \ --region $AWS_REGION \ --name $CLUSTER_NAME kubectl get nodesEKS Auto Mode 处理默认计算、Pod 网络、DNS、块存储和负载均衡集成并让LoadBalancer类型的 Service 可以直接生成 NLB。注意全新的 Auto Mode 集群上kubectl get nodes可能一开始返回No resources found这是正常现象——Auto Mode 在有 pending 工作负载需求时才 provision 计算节点等 Helm 安装后节点就会出现。准备 RDS MySQL 并放通数据库端口RDS 侧的具体 VPC 和子网命令因账户而异文档给出的是硬性要求MySQL 8 兼容引擎。数据库名openwork_den。位于与 EKS 集群相同 VPC 的私有子网。RDS 安全组入站 TCP3306来源是 EKS 节点/Pod 安全边界。开启存储加密和备份生产环境关闭公网访问。TLS 至少被支持required 或 supported。数据库 URL 示例mysql://openwork:passwordrds-endpoint:3306/openwork_den?sslacceptaccept其中password和rds-endpoint由你替换为自己的 RDS 用户密码和端点。?sslacceptaccept是私有 RDS 冒烟路径保留 TLS 但不要求把 RDS CA bundle 挂载进 OpenWork 镜像之后提供 RDS CA bundle 再改用sslmodeverify-ca或sslmodeverify-full这类严格校验值。等集群进入ACTIVE状态后同时放行来自 EKS 集群安全组和 eksctl 共享节点安全组的 MySQL 流量$RDS_SG_ID是你 RDS 实例的安全组 ID需要自行替换export CLUSTER_SG_ID$(aws eks describe-cluster \ --region $AWS_REGION \ --name $CLUSTER_NAME \ --query cluster.resourcesVpcConfig.clusterSecurityGroupId \ --output text) export NODE_SG_ID$(aws cloudformation describe-stacks \ --region $AWS_REGION \ --stack-name eksctl-${CLUSTER_NAME}-cluster \ --query Stacks[0].Outputs[?OutputKeySharedNodeSecurityGroup].OutputValue \ --output text) aws ec2 authorize-security-group-ingress \ --region $AWS_REGION \ --group-id $RDS_SG_ID \ --protocol tcp \ --port 3306 \ --source-group $CLUSTER_SG_ID aws ec2 authorize-security-group-ingress \ --region $AWS_REGION \ --group-id $RDS_SG_ID \ --protocol tcp \ --port 3306 \ --source-group $NODE_SG_ID安装 OpenWork 之前先用一个临时 MySQL 客户端 Pod 验证集群到 RDS 的网络可达性。这条命令会创建一个名为mysql-client的临时 Pod--rm表示执行完即删除$RDS_ENDPOINT替换为你的 RDS 端点执行时会提示输入密码kubectl run mysql-client \ --rm \ -it \ --restartNever \ --imagemysql:8 \ -- mysql \ --host$RDS_ENDPOINT \ --useropenwork \ --password \ --ssl-modeREQUIRED \ --execute select 1准备 Helm values主路径是 HTTPS 起点文件DNS 和 ACM 证书已就绪时使用cp packaging/helm/openwork-ee/examples/values.aws-load-balancer.yaml values.aws.yaml如果 DNS 和 ACM 还没准备好改用 HTTP 冒烟起点文件在 NLB 上走明文 HTTP 端口装完再切 HTTPS生产建议直接用上面的 HTTPS 版本cp packaging/helm/openwork-ee/examples/values.aws-load-balancer-http-smoke.yaml values.aws.yaml起点文件里所有REPLACE_*占位符都要替换对应关系如下以 values.aws-load-balancer.yaml 为准占位符替换为REPLACE_OPENWORK_VERSION已发布的 openwork-ee 图表版本号同时用于image.tagREPLACE_COMPANY_NAME/REPLACE_COMPANY_SLUG单组织名称与 slugREPLACE_ADMIN_EMAIL第一个 owner 的真实邮箱REPLACE_WEB_HOST/REPLACE_API_HOST你的 web 与 API 域名REPLACE_DB_PASSWORD/REPLACE_RDS_ENDPOINTRDS 用户密码与端点REPLACE_ACM_CERT_ARN同时覆盖 web 和 API 两个主机的 ACM 证书 ARNREPLACE_BOOTSTRAP_CODE一次性/setup管理员引导码见后文生成两个 Secret 值各用一次独立生成的输出且不要跨环境复用openssl rand -base64 48 openssl rand -base64 48第一个值填secret.values.betterAuthSecret第二个填secret.values.denDbEncryptionKey。需要发交易邮件时在同一个 values 文件里配置 SMTP这些值会渲染成 Den API 的EMAIL_FROM、SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS、SMTP_SECUREsecret: values: emailFrom: OpenWork no-replyexample.com smtpHost: smtp.example.com smtpPort: 587 smtpUser: openworkexample.com smtpPass: REPLACE_SMTP_PASSWORD smtpSecure: falseSMTP 投递要求EMAIL_FROM和SMTP_HOST同时存在只有在不启用 SMTP 邮件时才把smtpHost留空。两个容易踩的坑用 values 文件而不是长串--set参数。多个 OpenWork 值是逗号分隔字符串如config.public.corsOrigins普通--set解析很容易把它们弄坏。公共 URL 值放在config.public.*下数据库和应用 Secret 放在secret.values.*下。config.urls、config.databaseUrl或secrets.*这类键会被图表忽略。安装前先渲染图表确认迁移 Job 会拿到你的 RDS URLhelm template openwork-ee oci://ghcr.io/different-ai/charts/openwork-ee \ --version REPLACE_OPENWORK_VERSION \ --namespace openwork-ee \ -f values.aws.yaml /tmp/openwork-rendered.yaml grep -E DATABASE_URL|DEN_BASE_URL|DEN_WEB_PUBLIC_ORIGIN|EMAIL_FROM|SMTP_HOST|SMTP_PORT|SMTP_SECURE /tmp/openwork-rendered.yamlREPLACE_OPENWORK_VERSION换成你要发布的图表版本。分享渲染结果或终端输出前先脱敏。版本固定的一个细节--version同时钉住图表和镜像因为发布图表的appVersion等于其版本image.tag默认取该appVersion。0.18.46及更早的发布图表携带image.tag: latest每次拉取都会漂到最新 release。可以用下面命令检查某个版本的image.tag如果打印tag: latest安装时再额外传--set image.tagXX 为版本号helm show values oci://ghcr.io/different-ai/charts/openwork-ee --version X | grep -A1 ^image:安装 openwork-ee 图表已发布的图表在 GHCR 上主安装命令helm upgrade --install openwork-ee oci://ghcr.io/different-ai/charts/openwork-ee \ --version REPLACE_OPENWORK_VERSION \ --namespace openwork-ee \ --create-namespace \ -f values.aws.yaml冷集群首次安装建议追加--timeout 30m迁移 Job 使用 Den API 镜像activeDeadlineSeconds默认1800秒从 Job 创建开始计时包含节点首次拉取约 800 MB 镜像的时间而 Helm 默认--timeout只有5m0s不加的话 Helm 会在 Job 完成前就放弃。如果你是在仓库 checkout 里做本地测试可以直接装本地图表路径checkout 的Chart.yaml是占位appVersion必须显式给image.taghelm upgrade --install openwork-ee ./packaging/helm/openwork-ee \ --namespace openwork-ee \ --create-namespace \ --set image.tagREPLACE_OPENWORK_VERSION \ -f values.aws.yaml如果 GHCR 拉镜像报ImagePullBackOff公开发布不应需要额外认证出现该报错一般是私有包或私有 fork。需要时创建imagePullSecretskubectl create secret docker-registry ghcr-pull-secret \ --namespace openwork-ee \ --docker-serverghcr.io \ --docker-username$GITHUB_USER \ --docker-password$GITHUB_TOKENimagePullSecrets: - name: ghcr-pull-secret数据库迁移失败时先查迁移 Job迁移 Job 在 Deployment 和 Service 之前以pre-install,pre-upgradehook 运行。它失败时先修迁移再排查 web/API 就绪问题。注意共享报告时避免kubectl describe job openwork-ee-migrate因为 hook Job 当前会把DATABASE_URL和DEN_DB_ENCRYPTION_KEY渲染进 Job 环境。改用日志和已脱敏的渲染清单。需要保留日志做调试时临时关闭 hook 行为这会改变 Job 的删除/重试方式调试完要恢复migrations: enabled: true hook: false backoffLimit: 0helm upgrade --install openwork-ee oci://ghcr.io/different-ai/charts/openwork-ee \ --version REPLACE_OPENWORK_VERSION \ --namespace openwork-ee \ --create-namespace \ -f values.aws.yaml \ --waitfalse kubectl get jobs,pods -n openwork-ee kubectl logs -n openwork-ee -l job-nameopenwork-ee-migrate --all-containerstrue调试完成后恢复默认 hook 模式migrations: enabled: true hook: true backoffLimit: 2两个与 RDS 直接相关的现象迁移 Job 日志出现self-signed certificate in certificate chain说明在用严格证书校验但没有挂 RDS CA bundle。先用冒烟 URL 的?sslacceptaccept或先挂载/配置 RDS CA bundle 再切严格校验。首次安装报DeadlineExceeded且kubectl describe pod显示 Pod 还在Pulling这是镜像拉取超过了 deadline不是迁移本身失败。缓解办法是把openwork-den-api和openwork-den-web镜像镜像到集群就近的 registry设置denApi.image.repository/denWeb.image.repository或提前在节点上用容器运行时拉好 tagcrictl pull ghcr.io/different-ai/openwork-den-api:version默认image.pullPolicy: IfNotPresent会复用已拉取的镜像。首次安装失败后的恢复直接重跑同一条helm upgrade --install命令before-hook-creation删除策略会替换失败的 Job。只有当 Helm 报has no deployed releases或helm list显示 release 为pending-install时才需要helm uninstall后重装。指向 DNS 并启用 HTTPS等 AWS 分配负载均衡器主机名kubectl get svc -n openwork-ee应能看到openwork-ee-den-web和openwork-ee-den-api两个 Service 的 external 主机名。然后创建 DNS 记录openwork.example.com→ Den Web 负载均衡器主机名api.openwork.example.com→ Den API 负载均衡器主机名起点 values 在 NLB 的443端口终结 TLS再用明文 HTTP 转发到 Kubernetes service 目标端口。使用一份同时覆盖 web 和 API 两个主机的 ACM 证书denWeb: service: port: 443 annotations: service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:... service.beta.kubernetes.io/aws-load-balancer-ssl-ports: 443 denApi: service: port: 443 annotations: service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:... service.beta.kubernetes.io/aws-load-balancer-ssl-ports: 443arn:aws:acm:...替换为你自己的 ACM 证书 ARN。生产域名建议先上 HTTPS 再测 SSO浏览器认证 Cookie 和 IdP 回调策略在稳定的 HTTPS origin 上比裸负载均衡主机名好验证得多。DNS/TLS 没就绪时的临时 HTTP 冒烟路径去掉 SSL 注解把denWeb.service.port改回3005、denApi.service.port改回8788并在values.aws.yaml里用显式的http://host:portorigin。如果暂时仍用裸 AWS 负载均衡主机名临时更新对应的config.public.*origin 再跑一次helm upgrade不要让生产部署长期停留在裸负载均衡主机名上。当前图表在 ConfigMap 或 Secret 内容变化时会自动滚动 Den API、Den Web 和 Gateway Pod。旧版本图表则需要手动重启kubectl rollout restart deployment/openwork-ee-den-api deployment/openwork-ee-den-web -n openwork-ee kubectl rollout status deployment/openwork-ee-den-api -n openwork-ee --timeout180s kubectl rollout status deployment/openwork-ee-den-web -n openwork-ee --timeout180s验证就绪先查 Kubernetes 状态helm status openwork-ee -n openwork-ee kubectl get pods -n openwork-ee kubectl get jobs -n openwork-ee kubectl describe pods -n openwork-ee kubectl logs -n openwork-ee deploy/openwork-ee-den-api kubectl logs -n openwork-ee deploy/openwork-ee-den-web再从本机检查服务就绪端点。DNS 和 HTTPS 就绪后curl -fsS https://api.openwork.example.com/ready curl -fsS https://openwork.example.com/api/readyHTTP 冒烟阶段改用裸 NLB 主机名和端口REPLACE_API_NLB_HOST/REPLACE_WEB_NLB_HOST替换为kubectl get svc -n openwork-ee输出里的两个 external 主机名curl -fsS http://REPLACE_API_NLB_HOST:8788/ready curl -fsS http://REPLACE_WEB_NLB_HOST:3005/api/ready就绪探针的约定是den-api 用GET /ready、den-web 用GET /api/readyliveness 分别对应/health和/api/healthNLB 健康检查路径也正是这两条所以 NLB 健康与 Pod 就绪探针是同一组端点。创建第一个管理员图表默认single_org。首次登录前在 values 里配置单组织config: tenancy: mode: single_org singleOrgName: Acme singleOrgSlug: acme ownerEmails: adminacme.com requireEmailVerification: false public: bootstrapAdminEmails: adminacme.com secret: values: initialAdminBootstrapCode: REPLACE_BOOTSTRAP_CODE包含 initial-administrator bootstrap 的 release 里推荐把文档化的一次性 setup secret 通过secret.existingSecret指向的 Kubernetes Secret 注入不要把代码直接留在 values 文件或 ConfigMap 里AWS 起点示例文件保留了secret.values.initialAdminBootstrapCode字段两者按你的发布版本二选一以该版本 release 文档为准。然后打开https://openwork.example.com/setup输入配置好的 owner 邮箱和一次性 operator 码创建第一个账户。OpenWork 会创建单例组织、授予 owner 和已配置的 platform-admin 权限并登录管理员公共注册保持关闭。第一个用户存在后setup 码不能再引导另一个账户。ownerEmails和bootstrapAdminEmails只授权角色都不会创建账户或密码不存在默认管理员密码。没有/setup路由的图表版本不支持私有初始管理员引导需要先升级再执行这一步。症状速查现象可能原因处理CloudShell 里没有helmCloudShell 不一定自带 Helm在 CloudShell 装 Helm或本地用 AWS 凭据跑 Helmaws sts get-caller-identity返回NoCredentialsAWS CLI 未认证配置 AWS SSO/profile 或用已认证的 CloudShell首次kubectl get nodes为空Auto Mode 尚未需要 provision 节点集群 active 后继续Pod 变 pending 时节点会出现Pod 显示未容忍的 Auto Mode taintAuto Mode 还在选择/provision 容量等 NodeClaim再查 Pod 事件Pod sandbox 报aws-cni failed ... failed to assign an IP address子网/IP 或 EKS CNI 容量问题查子网空闲 IP 和节点事件等 Auto Mode 提供替换容量后重试迁移 Job 连不上 MySQLRDS 安全组、数据库凭据或 TLS 模式错误放行 TCP3306用mysql-clientPod 验证私有 RDS 冒烟路径用?sslacceptaccept迁移日志出现self-signed certificate in certificate chain严格证书校验但没挂 RDS CA bundle用?sslacceptaccept或先配置 RDS CA bundle 再严格校验运行时就绪但迁移失败Helm hook 未完成先查kubectl get jobs和迁移 Job 日志再测 webGHCRImagePullBackOff私有镜像或缺少 pull token添加imagePullSecrets浏览器认证循环或 CORS 错误公共 origin 与 DNS/TLS 不匹配把webOrigin、apiOrigin、corsOrigins、betterAuthTrustedOrigins、authCallbackUrl都设为最终 HTTPS 域名测试后的清理以下命令不可逆helm uninstall删除该 release 的全部资源eksctl delete cluster删除整个集群及其托管资源。只在确认是一次性测试环境时执行helm uninstall openwork-ee -n openwork-ee eksctl delete cluster --name $CLUSTER_NAME --region $AWS_REGION如果 RDS 快照、Secrets Manager secret、Route 53 记录、ACM 证书和手工创建的安全组只服务于这次测试也一并删除。【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考