更夫 Gengfu

主题

关于本页

本页介绍更夫所基于的开源内核 Keep 的通用能力。更夫在其上提供国内化增强：钉钉/企业微信/飞书通知、国产大模型接入、LDAP 认证与值班管理。部署与上手请看快速上手。

关于使用 oauth2‑proxy 和 NGINX Ingress Controller 为您的自托管 GitLab 向 Keep 添加单点登录的分步烹饪书。

下面使用的约定

  • <keep-host>             – 用户访问 Keep 的公共 FQDN（例如 keep.example.com）
  • <gitlab-host>           – 您的 GitLab 实例的 URL（例如 gitlab.example.com）
  • <registry-host>         – 存储镜像的容器注册表（如果使用公共镜像则省略）
  • Kubernetes 命名空间 keep – 如果您喜欢其他命名空间，可以随意在任何地方更改。

1. 前置条件 ​

内容原因
Kubernetes 集群和 keep 命名空间Keep、oauth2‑proxy 和服务所在的位置
ingress‑nginx（或兼容）提供 oauth2‑proxy 使用的 auth_request 功能
GitLab 15+ 在 https://<gitlab-host>OpenID‑Connect 发行者
Helm 3.x 和离线 charts/镜像（可选）如果您的集群没有互联网出口

2. 创建 GitLab OAuth 应用程序 ​

  1. GitLab ▸ Admin → Applications → New
  2. 名称 → keep‑sso
  3. 重定向 URI → https://<keep-host>/oauth2/callback
  4. 范围 → openid profile email（+ 如果您计划按组/项目限制访问，则添加 read_api）
  5. 保存 – 复制生成的 Application ID 和 Secret。

3. Kubernetes 密钥和配置 ​

bash
# 3.1 生成一个 32 字节的 cookie 密钥
echo "$(openssl rand -base64 32 | head -c 32 | base64)" > cookie.b64

# 3.2 存储 GitLab 凭证和 cookie 密钥
kubectl -n keep create secret generic oauth2-proxy \
  --from-literal=client-id=<GITLAB_APP_ID> \
  --from-literal=client-secret=<GITLAB_APP_SECRET> \
  --from-file=cookie-secret=cookie.b64

# 3.3 使用 OAUTH2_PROXY ENV 变量添加 gitlab 凭证和 cookie 密钥
OAUTH2_PROXY_CLIENT_ID=<GITLAB_APP_ID>
OAUTH2_PROXY_CLIENT_SECRET=<GITLAB_APP_SECRET>
OAUTH2_PROXY_COOKIE_SECRET=cookie.b64

# (optional) 存储 GitLab 的自定义 CA 证书
kubectl -n keep create secret generic gitlab-ca \
  --from-file=gitlab-ca.pem
yaml
# 3.4 oauth2_proxy.cfg (ConfigMap)
apiVersion: v1
kind: ConfigMap
metadata:
  name: oauth2-proxy
  namespace: keep
data:
  oauth2_proxy.cfg: |
    email_domains = ["*"]
    upstreams     = ["file:///dev/null"]   # 我们只使用 auth-request 模式
    provider      = "gitlab"
    cookie_name   = "keep-dev" #如果为空，将使用默认 cookie 名称：_oauth2_proxy
    cookie_secure = true

4. 部署 oauth2‑proxy (Helm) ​

yaml
# values.oauth2-proxy.yaml – 最小基线
image:                     # 如果需要，替换为公共镜像
  repository: <registry-host>/oauth2-proxy/oauth2-proxy
  tag: v7.9.0

config:
  configFile: |-
    # 内容来自上面的 ConfigMap

extraArgs:
  oidc-issuer-url: https://<gitlab-host>
  set-xauthrequest: "true"            # 添加 X-Auth-Request-*/X-Forwarded-* 头
  pass-authorization-header: "true"   # 添加 Authorization: Bearer <id_token>
  # provider-ca-file: /ca/gitlab-ca.pem   # 如果您挂载了企业 CA 或使用 ssl-insecure-skip-verify: "true" 来禁用 SSL 检查，则启用。
extraVolumes:
  - name: gitlab-ca
    secret:
      secretName: gitlab-ca
extraVolumeMounts:
  - name: gitlab-ca
    mountPath: /ca/gitlab-ca.pem
    subPath: gitlab-ca.pem
    readOnly: true

service:
  type: ClusterIP

ingress:
  enabled: false   # 我们只需要一个内部 Service
bash
helm repo add oauth2-proxy https://oauth2-proxy.github.io/manifests
helm upgrade --install oauth2-proxy oauth2-proxy/oauth2-proxy \
     -n keep -f values.oauth2-proxy.yaml

仅实验室快捷方式：而不是挂载 CA，您可以暂时添加 ssl-insecure-skip-verify: "true" 在 extraArgs 下。

5. 修补（或创建）Keep 的 Ingress 资源 ​

添加三个注解，以便 ingress‑nginx 将 auth 委托给 Service：

yaml
global:
  ingress:
    annotations:
      nginx.ingress.kubernetes.io/auth-url: "http://oauth2-proxy.keep.svc.cluster.local/oauth2/auth"
      nginx.ingress.kubernetes.io/auth-signin: "https://<keep-host>/oauth2/start?rd=$request_uri"
      nginx.ingress.kubernetes.io/auth-response-headers: "authorization,x-auth-request-user,x-auth-request-email,x-forwarded-user,x-forwarded-email,x-forwarded-groups"

重新部署 Keep（或手动修补 Ingress）。

6. Keep 的环境变量 ​

yaml
backend:
  env:
    - name: AUTH_TYPE
      value: OAUTH2PROXY
    - name: KEEP_OAUTH2_PROXY_USER_HEADER
      value: x-auth-request-email
    - name: KEEP_OAUTH2_PROXY_ROLE_HEADER
      value: x-auth-request-groups
    - name: KEEP_OAUTH2_PROXY_AUTO_CREATE_USER
      value: true
    - name: KEEP_OAUTH2_PROXY_ADMIN_ROLES
      value: <将在您的 keep ui 中具有管理员角色的 gitlab 组>
    - name: KEEP_OAUTH2_PROXY_NOC_ROLES
      value: <将无法访问您的 keep ui 的 gitlab 组>

frontend:
  env:
    # **浏览器**应使用的公共 URL
    - name: NEXTAUTH_URL
      value: "https://<keep-host>"

    # **服务器端** Next.js 代码始终可以到达的 URL
    - name: NEXTAUTH_URL_INTERNAL
      value: "http://keep-frontend.keep.svc.cluster.local:3000"

    # API URL
    - name: API_URL_CLIENT   # 浏览器 → ingress
      value: "/v2"
    - name: API_URL          # 服务器 → 后端 Service（无 auth-proxy）
      value: "http://keep-backend.keep.svc.cluster.local:8080"

    #Oauth2-Proxy
    - name: AUTH_TYPE
      value: OAUTH2PROXY
    - name: KEEP_OAUTH2_PROXY_USER_HEADER
      value: x-auth-request-email
    - name: KEEP_OAUTH2_PROXY_ROLE_HEADER
      value: x-auth-request-groups

部署 frontend：

bash
kubectl -n keep rollout restart deploy/keep-frontend

7. 快速验证 ​

bash
# 7.1 在没有 cookie 的情况下调用 auth 端点 – 预期 401
curl -I http://oauth2-proxy.keep.svc.cluster.local/oauth2/auth

# 7.2 从浏览器会话复制 keep-dev cookie
curl -I --cookie "keep-dev=<COOKIE>" \
     http://oauth2-proxy.keep.svc.cluster.local/oauth2/auth   # 预期 200

浏览器冒烟测试：

  • https://<keep-host> → 重定向到 GitLab → 登录 → 返回 Keep。
  • DevTools ▸ Network → /api/auth/session 返回 200。

8. 故障排除 ​

症状常见原因和解决方案
TLS 错误 x509: certificate signed by unknown authority挂载您的 GitLab CA（provider-ca-file）或设置 ssl-insecure-skip-verify=true（仅限开发）。
Ingress 日志 auth request unexpected status: 502auth-url 指向外部主机 – 使用内部 Service DNS（http://oauth2-proxy.keep.svc.cluster.local）。
浏览器在 /signin?callbackUrl=… 处循环① set-xauthrequest 未启用，或 ② auth-response-headers 未设置，或 ③ 后端通过 oauth2‑proxy 接收调用（API_URL 错误）。
重定向到 0.0.0.0:3000 或 pod 名称NEXTAUTH_URL 在构建时缺失；重建 UI 或覆盖 env。
即使有 cookie 也从 /oauth2/auth 收到 401Cookie 过期/时钟不同步。清除 cookie 并重新登录。

9. 清理 ​

bash
helm -n keep uninstall oauth2-proxy
helm -n keep uninstall keep          # 如果您想删除 Keep
kubectl -n keep delete secret oauth2-proxy gitlab-ca
bash
openssl rand -hex 16 | xxd -r -p | base64

附录 B – 将镜像同步到离线注册表（示例） ​

bash
skopeo copy docker://quay.io/oauth2-proxy/oauth2-proxy:v7.9.0 \
             docker://<registry-host>/oauth2-proxy/oauth2-proxy:v7.9.0

基于 MIT 协议开源的 Keep · 由更夫社区维护

© 2025-2026 更夫 Gengfu