企业官网建设流程全解析

OpenWork EE 在 AWS EKS 上使用 Helm 部署实战指南（含 RDS MySQL 与 NLB 配置）

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork

本指南以开源仓库 docs/aws-eks-helm.md 为骨架，完整讲解如何在 Amazon EKS 上通过官方 Helm Chart 部署 OpenWork EE 自托管实例：从 EKS Auto Mode 集群创建、RDS MySQL 私有网络接入、双 Network Load Balancer 暴露 Web/API，到首任管理员引导、SSO 接入与故障排查。读完本文，你将掌握一套可直接复制的 AWS 生产级（或近似生产级）自托管部署流程，并能结合 openwork-ee Helm Chart 源码理解每个配置项背后的渲染逻辑与运行原理。

一、这次部署会得到什么

本部署路径是 OpenWork EE 自托管在 AWS 上的推荐首选项，最终产出：

• Den API（控制平面），监听端口8788；
• Den Web（Web 应用），监听端口3005；
• 可选的OpenWork Gateway服务，默认关闭（由inference.enabled/gateway.enabled控制）；
• 一个RDS MySQL数据库；
• 一个单组织（single-org）的 OpenWork 部署；
• 默认创建两个公网 AWS Network Load Balancer：一个给 Web，一个给 API。

责任边界划分明确：AWS 负责EKS 集群、节点生命周期、VPC 网络、负载均衡器、RDS、DNS、TLS 证书、IAM 与安全组；OpenWork Helm Chart 负责OpenWork 的 Deployment、Service、ConfigMap、Secret、健康探针以及数据库迁移 Job。这一点从仓库的 chart 结构可以直接印证——templates 目录下den-api.yaml、den-web.yaml、configmap.yaml、secret.yaml、migration-job.yaml与 chart 自身的管理范围完全对应。

二、为什么选 Helm on EKS 而不是其他方案

指南给出的判断依据很务实：

• OpenWork EE 的发布产物本身就是一个 Helm Chart，服务拆分（Den API / Den Web / Gateway）天然映射到 Kubernetes 工作负载；
• EKS Auto Mode 免去了客户路径上大部分节点与负载均衡器的手工搭建；
• VM 或 ECS 指南并非不可行，但那是另一套需要长期维护的打包面。

AWS 实测发现的关键缺口不是 Helm 本身，而是缺少 AWS 专属的基础设施指引以及chart 缺少 AWS Service 注解的旋钮。前者由本指南补齐，后者已由 chart 在denApi.service/denWeb.service上支持annotations、loadBalancerClass等配置解决（见下文示例与 values.yaml）。

三、前置条件

• AWS CLI 已认证到目标账号；
• 本机安装kubectl、helm、eksctl；
• eksctl版本0.195.0 或更新（EKS Auto Mode 需要）；
• 具备创建 EKS、EC2/VPC、IAM、Elastic Load Balancing、RDS、Secrets Manager、Route 53、ACM 资源的权限；
• 一个真实的管理员邮箱（用于首个 owner 账户）；
• 一个你控制的域名，例如openwork.example.com与api.openwork.example.com。

安全红线：不要用 AWS root 账号跑生产安装。请使用 AWS SSO 或仅含集群、VPC/负载均衡、RDS、DNS、证书所需权限的 IAM 角色。

四、CloudShell 快速开始

从 AWS 控制台出发时，CloudShell 可以当作测试环境，但它不一定自带全部工具，也可能没有默认 region。务必显式设置 region，即使控制台 region 选择器已经显示正确：

export AWS_REGION=us-east-1 aws sts get-caller-identity aws configure get region

若缺少工具，安装固定版本的 Helm 与eksctl。安装前务必用该精确版本官方发布的校验和验证每个归档：

HELM_VERSION=v3.18.4 HELM_ARCHIVE="helm-${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_VERSION=v0.195.0 EKSCTL_ARCHIVE=eksctl_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 值。更新 pin 时，务必连同校验和一起从官方对应发布替换，而不是只改版本号。

五、创建 EKS 集群（Auto Mode）

首次部署直接创建一个 EKS Auto Mode 集群：

export AWS_REGION=us-east-1 export CLUSTER_NAME=openwork-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 nodes

EKS Auto Mode 负责默认计算、Pod 网络、DNS、块存储与负载均衡集成，并让 KubernetesLoadBalancer类型的 Service 可以直接获得 AWS Network Load Balancer。

常见认知误区：全新的 Auto Mode 集群最初可能没有任何节点。Auto Mode 会在出现待调度工作负载时才供给计算资源，因此在第一批 Pod 被调度前，kubectl get nodes返回No resources found是正常现象，不代表集群异常。

六、创建 RDS MySQL 数据库

创建一个可从 EKS worker 安全组访问的 MySQL 数据库。具体 VPC 与子网命令因账号而异，以下是必须满足的硬性要求：

• RDS MySQL 8 兼容引擎；
• 数据库名：openwork_den；
• 与 EKS 集群同 VPC 的私有子网；
• RDS 安全组入站 TCP3306放行自 EKS 节点/Pod 安全组；
• 开启存储加密；
• 开启备份；
• 生产环境关闭公网访问；
• 至少支持（生产建议强制）TLS。

示例数据库 URL：

mysql://openwork:<password>@<rds-endpoint>:3306/openwork_den?sslaccept=accept

关于sslaccept=accept的底层原理

?sslaccept=accept是私有 RDS 冒烟路径的推荐写法：保持 TLS 加密但不要求把 RDS CA 捆绑包挂载进 OpenWork 镜像。等后续准备好 CA 后，再用sslmode=verify-ca或sslmode=verify-full这类严格模式。

这一行为可以直接在仓库源码中验证。Den 的 MySQL 连接解析器 ee/packages/den-db/src/mysql-config.ts 将 URL 中的sslaccept/sslmode参数解析为rejectUnauthorized布尔值：

• sslaccept=strict、sslmode=verify-ca、sslmode=verify-full、sslmode=require→rejectUnauthorized = true（严格校验证书链）；
• sslaccept=accept→ TLS 开启但不做证书链校验，因此不要求挂载 CA 包。

所以在严格验证前，要么走?sslaccept=accept冒烟路径，要么先挂载/配置 RDS CA 捆绑包。chart 也提供了customCa配置（见 chart README 的 Custom CA 章节），可将 CA 挂载为/etc/openwork/custom-ca/ca-bundle.pem并设置NODE_EXTRA_CA_CERTS。

安全组放行

等 EKS 集群进入ACTIVE后再接线 RDS 安全组。需要同时放行来自 EKS 集群安全组和 eksctl 共享节点安全组的 MySQL 流量：

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[?OutputKey==`SharedNodeSecurityGroup`].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"

安装前验证网络连通性

一个简单可靠的方式是临时跑一个 MySQL 客户端 Pod：

kubectl run mysql-client \ --rm \ -it \ --restart=Never \ --image=mysql:8 \ -- mysql \ --host="$RDS_ENDPOINT" \ --user=openwork \ --password \ --ssl-mode=REQUIRED \ --execute "select 1"

七、准备 Helm values

复制起始配置文件：

cp packaging/helm/openwork-ee/examples/values.aws-load-balancer.yaml values.aws.yaml

如果 DNS 与 ACM 尚未就绪，改用 HTTP 冒烟测试起始文件：

cp packaging/helm/openwork-ee/examples/values.aws-load-balancer-http-smoke.yaml values.aws.yaml

然后替换所有REPLACE_*占位符。首先生成两个互相独立的随机 secret：

openssl rand -base64 48 openssl rand -base64 48

第一个用于secret.values.betterAuthSecret，第二个用于secret.values.denDbEncryptionKey。两个值都不要跨环境复用。

配置 SMTP 事务邮件

在同一 values 文件中配置 SMTP：

secret: values: emailFrom: "OpenWork <no-reply@example.com>" smtpHost: "smtp.example.com" smtpPort: "587" smtpUser: "openwork@example.com" smtpPass: "REPLACE_SMTP_PASSWORD" smtpSecure: "false"

这些值在 Den API 中会成为EMAIL_FROM、SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS、SMTP_SECURE。若使用secret.create=false，则需把这些键加到secret.existingSecret引用的既有 Kubernetes Secret 中（键映射见 secret.yaml 模板 与 values.yaml 的 secret.keys）。SMTP 投递同时要求EMAIL_FROM与SMTP_HOST；只有想禁用 SMTP 事务邮件时才把smtpHost留空。

使用 values 文件而非--set长串

几个 OpenWork 值是逗号分隔字符串，例如config.public.corsOrigins，裸--set解析常常会破坏它们。务必使用 values 文件。

当前 chart 的键位

请确认文件使用当前 chart 键位：

• 公网 URL 值放在config.public.*下；
• 数据库与应用 secret 放在secret.values.*下；
• config.urls、config.databaseUrl、secrets.*这类旧键会被 chart忽略。

从 configmap.yaml 可以看到config.public.webOrigin被渲染为DEN_BASE_URL，并作为兼容别名同时输出BETTER_AUTH_URL、DEN_WEB_PUBLIC_ORIGIN、DEN_AUTH_ORIGIN、DEN_WEB_OPENWORK_AUTH_CALLBACK_URL等；而apiOrigin、corsOrigins、betterAuthTrustedOrigins、webAppHosts等仅在非空时渲染为对应DEN_*变量。这正是"当前 chart 以webOrigin为单一主公网源"的代码级证据。

安装前渲染校验

安装前先渲染 chart，确认迁移 Job 会使用你的 RDS URL：

helm 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.yaml

分享渲染后的清单或终端输出前，务必先脱敏 secret。

版本与镜像 tag 的对应关系

chart 的镜像 tag 解析遵循"组件 tag →image.tag→Chart.appVersion"的优先级（见 _helpers.tpl 的 imageTag 定义）。已发布的 chart 在打包时以--app-version <release>盖章，因此--version X就会部署 X 版本的镜像，无需额外设置。仓库 checkout 安装时appVersion是占位符（见 Chart.yaml），此时必须显式--set image.tag=REPLACE_OPENWORK_VERSION。

八、安装 OpenWork

官方 chart 发布在 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

仓库 checkout 本地测试：

helm upgrade --install openwork-ee ./packaging/helm/openwork-ee \ --namespace openwork-ee \ --create-namespace \ -f values.aws.yaml

冷集群首次安装建议额外传--timeout 30m：迁移 hook Job 需要拉取约 800 MB 的 Den API 镜像，Helm 默认 5 分钟超时可能先于 Job 放弃。

GHCR 拉取失败（ImagePullBackOff）

如果 GHCR 镜像拉取报ImagePullBackOff，先向 GHCR 认证并添加imagePullSecrets。公开发布通常不需要，但私有包或私有 fork 需要：

kubectl create secret docker-registry ghcr-pull-secret \ --namespace openwork-ee \ --docker-server=ghcr.io \ --docker-username="$GITHUB_USER" \ --docker-password="$GITHUB_TOKEN"

imagePullSecrets: - name: ghcr-pull-secret

九、迁移 Job 故障排查

迁移 Job 在 Deployment 与 Service 安装之前运行（Helm hook 权重-5，见 migration-job.yaml）。它失败时，先修它，再排查 Web/API 就绪问题。

安全警告：不要在共享报告中直接kubectl describe job openwork-ee-migrate。当前 hook Job 在渲染出的环境里包含DATABASE_URL与DEN_DB_ENCRYPTION_KEY（secret.create=true时以明文value形式内联，见模板第 55-65 行），因为 pre-install hook 在常规 chart 资源之前运行。请改用日志和脱敏后的渲染清单。

保留日志的调试方式

临时关闭 hook 行为：

migrations: enabled: true hook: false backoffLimit: 0

然后运行 Helm 并查看普通 Job 日志：

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 \ --wait=false kubectl get jobs,pods -n openwork-ee kubectl logs -n openwork-ee -l job-name=openwork-ee-migrate --all-containers=true

如果出现针对 RDS 的self-signed certificate in certificate chain，改用文档推荐的私有 RDS 冒烟 URL?sslaccept=accept，或在启用严格证书校验前挂载/配置 RDS CA 捆绑包（原理见第六节的mysql-config.ts解析逻辑）。

调试完成后恢复默认 hook 模式：

migrations: enabled: true hook: true backoffLimit: 2

迁移 Job 的默认行为

默认 hook 执行的是 Den API 镜像内已编译的 Den DB bootstrap runner（node /app/ee/packages/den-db/dist/scripts/bootstrap.js）。在完全空库上，它先应用构建期的当前 schema SQL 快照、把已提交迁移记为基线，再用 Drizzle ORM 跑待执行迁移；在无 Drizzle ledger 的既有 schema 上，会先记录基线再迁移。相关配置默认值（activeDeadlineSeconds: 1800、hookDeletePolicy: before-hook-creation,hook-succeeded等）见 values.yaml。首次安装出现DeadlineExceeded且 Pod 仍处于Pulling状态，通常意味着镜像拉取超过了 deadline，而不是迁移本身失败。

十、把 DNS 指向 AWS 负载均衡器

等待 AWS 分配负载均衡器主机名：

kubectl get svc -n openwork-ee

应能看到以下两个 Service 的外部主机名：

• openwork-ee-den-web
• openwork-ee-den-api

创建两条 DNS 记录：

• openwork.example.com→ Den Web 负载均衡器主机名；
• api.openwork.example.com→ Den API 负载均衡器主机名。

起始 values 让每个 NLB 在443端口终结 TLS，并把明文 HTTP 转发到 Kubernetes Service target port。ACM 证书要同时覆盖 Web 与 API 两个主机：

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: "443"

完整的 AWS 起始配置可参考 values.aws-load-balancer.yaml。其中还包含其他关键注解，值得逐条对照：

• loadBalancerClass: eks.amazonaws.com/nlb：显式指定 NLB；
• service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing：公网 NLB；
• service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip：IP 目标模式（Auto Mode 的推荐形态）；
• 健康检查注解分别指向den-api的/ready与den-web的/api/ready——这与 chart 依赖感知的就绪探针路径一致（见 den-api.yaml 模板 及 chart README 的 Health Probes 章节）。

生产域名优先在测试 SSO 之前启用 HTTPS。浏览器认证 cookie 与身份提供商回调策略在稳定 HTTPS origin 上远比裸负载均衡器主机名容易验证。

临时 HTTP-only 冒烟测试：去掉 SSL 注解，把denWeb.service.port改回3005、denApi.service.port改回8788，并在values.aws.yaml中使用显式http://host:portorigin。对应的完整示例见 values.aws-load-balancer-http-smoke.yaml（其webOrigin/apiOrigin等均以pending-*-nlb占位，首次安装成功后替换为真实 NLB 主机名再helm upgrade）。

如果仍在 DNS/TLS 就绪前使用裸 AWS 负载均衡器主机名，可临时更新values.aws.yaml中对应的config.public.*origin 后重新helm upgrade。但生产部署绝不要停留在裸负载均衡器主机名上。

关于配置变更的自动滚动

当前 chart 在 Den API、Den Web、Gateway Pod 的注解中注入 ConfigMap 与 Secret 的 sha256 校验和（见 den-api.yaml 模板第 47-49 行），因此 ConfigMap 或 Secret 内容变化时 Pod 会自动滚动。旧版 chart 上，改完公网 origin 需要手动重启：

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 --timeout=180s kubectl rollout status deployment/openwork-ee-den-web -n openwork-ee --timeout=180s

十一、验证就绪状态

检查 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

从你的机器检查服务就绪：

curl -fsS https://api.openwork.example.com/ready curl -fsS https://openwork.example.com/api/ready

HTTP 冒烟测试时使用裸 NLB 主机名与端口：

curl -fsS http://REPLACE_API_NLB_HOST:8788/ready curl -fsS http://REPLACE_WEB_NLB_HOST:3005/api/ready

chart 的探针体系与这些路径一一对应：den-api存活探针GET /health、就绪探针GET /ready；den-web存活探针GET /api/health、就绪探针GET /api/ready（见 chart README），默认探针参数（延迟、周期、超时、失败阈值）见 values.yaml。

十二、引导第一个 owner

chart 默认single_org模式。首次登录前设置以下值：

config: tenancy: mode: single_org singleOrgName: "Acme" singleOrgSlug: "acme" ownerEmails: "admin@acme.com" requireEmailVerification: "false" public: bootstrapAdminEmails: "admin@acme.com" secret: values: initialAdminBootstrapCode: "REPLACE_BOOTSTRAP_CODE"

对于包含 initial-administrator bootstrap 的发布版本，一次性 setup secret 应通过secret.existingSecret引用的 Kubernetes Secret 注入（键名默认DEN_INITIAL_ADMIN_BOOTSTRAP_CODE，见 values.yaml），不要把该 code 放进 values 文件或 ConfigMap。

然后打开https://openwork.example.com/setup，输入配置的 owner 邮箱与一次性操作员 code，创建第一个账户。OpenWork 会创建单例组织、授予 owner 与配置的平台 admin 权限并直接登录管理员。公网注册保持关闭。首个用户存在后，setup code 无法再引导第二个账户。

需要明确：ownerEmails与bootstrapAdminEmails只授权角色，都不会创建账户或密码，系统也没有默认管理员密码。二者的分工（前者控制单例组织所有权、后者控制平台 admin 白名单）在 chart README 的 Initial Organization Setup 章节 有详细说明。不含/setup路由的 chart 版本不支持私有初始管理员引导，必须先升级。

十三、用测试 IdP 配置 SSO

自托管安装默认关闭 plan gating（除非显式设置DEN_PLAN_GATING_ENABLED=true），因此 EE 自托管默认即可使用 SSO 管理。

先用OIDC做冒烟测试，因为大多数 IdP 都提供 discovery metadata。Auth0、Okta trial、Microsoft Entra 测试租户都是可行的演示 IdP。

在 IdP 应用里配置回调地址：

https://openwork.example.com/api/auth/sso/callback/openwork-sso-<org-id>

在 OpenWork 中：以 owner 身份登录 → 打开组织 SSO 设置 → 填入 IdP issuer/client 信息。保存后组织登录路径为：

https://openwork.example.com/sso/<singleOrgSlug>

对于SAML，OpenWork 会在 SAML 连接注册后展示生成的 ACS URL 与 metadata URL，直接在 IdP 中使用这些值，不要自己猜测。OpenWork 会拒绝未签名或弱签名的 SAML 响应，因此要让 IdP 对断言签名。

SSO 配置完成后，根登录页对单组织显示 SSO-only 体验，该组织的密码登录会被拒绝。

十四、故障排查速查表

十五、清理

一次性测试环境的清理：

helm uninstall openwork-ee -n openwork-ee eksctl delete cluster --name "$CLUSTER_NAME" --region "$AWS_REGION"

若仅用于测试，还要删除 RDS 快照、Secrets Manager 密钥、Route 53 记录、ACM 证书，以及手工创建的安全组。

延伸阅读：完整 chart 配置参考见 packaging/helm/openwork-ee/README.md，AWS 起始 values 见 values.aws-load-balancer.yaml 与 values.aws-load-balancer-http-smoke.yaml；Azure（AKS）、Google Cloud（GKE）对应的部署路径分别记录在 docs/azure-aks-helm.md 与 docs/gcp-gke-helm.md。

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork