
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具,协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题,请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可:
请先完整阅读并严格遵守以下文档中的全部规则与要求:
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前,不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式,不推荐豆包 AI;Cursor 等编辑器可在对话 @ 该链接,或加入 User Rules。 若 AI 无法访问外链,可 打开说明文档 复制全文粘贴。文档会随站点更新,复制内容可能过期,建议定期检查。
https://img.shields.io/github/stars/vouch/vouch-proxy.svg](https://github.com/vouch/vouch-proxy) https://goreportcard.com/badge/github.com/vouch/vouch-proxy](https://goreportcard.com/report/github.com/vouch/vouch-proxy) https://img.shields.io/badge/license-MIT-green.svg](https://github.com/vouch/vouch-proxy/blob/master/LICENSE) https://img.shields.io/docker/pulls/voucher/vouch-proxy.svg](https://hub.docker.com/r/voucher/vouch-proxy/) https://img.shields.io/github/v/tag/vouch/vouch-proxy.svg?sort=semver&color=green](https://github.com/vouch/vouch-proxy)
基于 http://nginx.org/en/docs/http/ngx_http_auth_request_module.html 模块的 Nginx 单点登录(SSO)解决方案。Vouch Proxy 可一次性保护您所有的网站。
Vouch Proxy 支持多种 OAuth 和 OIDC 登录提供商,并可强制通过以下身份提供商进行身份验证:
如果您已使用偏好的身份提供商(IdP)或库部署了 Vouch Proxy,请告知我们,以便我们更新列表。
若 Vouch 与 Nginx 反向代理运行在同一主机上,从 /validate 端点到 Nginx 的响应时间应小于 1ms。
Vouch Proxy(VP)强制访问者在访问网站前通过身份提供商(IdP)登录并认证(如上述列出的服务)。
!https://github.com/vouch/vouch-proxy/blob/master/examples/nginx-vouch-private_simple.png?raw=true
VP 也可用作单点登录(SSO)解决方案,保护同一域下的所有 Web 应用。
!https://github.com/vouch/vouch-proxy/blob/master/examples/nginx-vouch-private_appA_appB_appC.png?raw=true
访问者登录后,Vouch Proxy 在数小时内允许其访问受保护网站。每个请求都会被 VP 检查以确保有效性。
VP 可将身份提供商提供的访问者***、姓名及其他信息(包括访问令牌)通过 HTTP 头发送给 Web 应用,完全替代应用的用户管理功能。
Vouch Proxy 依赖 Vouch Proxy 服务器与受保护应用之间共享 Cookie 的能力。通常通过将 Vouch 部署在子域(如 vouch.yourdomain.com),应用部署在 app1.yourdomain.com 和 app2.yourdomain.com 实现。受保护域为 .yourdomain.com,需通过设置 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example#L23-L33 包含 yourdomain.com,或有时通过设置 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example#L81-L82 为 yourdomain.com,确保 Vouch Proxy Cookie 在此域下设置。
cp ./config/config.yml_example_$OAUTH_PROVIDER ./config/config.yml/auth 端点以下 Nginx 配置假设:
vouch.yourdomain.com 和 protectedapp.yourdomain.com 运行在同一服务器https 提供服务并拥有有效证书(若未使用 HTTPS,将 listen 改为 80 并设置 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example#L84-L85 为 false)server { listen 443 ssl http2; server_name protectedapp.yourdomain.com; root /var/www/html/; ssl_certificate /etc/letsencrypt/live/protectedapp.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/protectedapp.yourdomain.com/privkey.pem; # 将所有请求发送至 `/validate` 端点进行授权 auth_request /validate; location = /validate { # 将 /validate 请求转发至 Vouch Proxy proxy_pass http://127.0.0.1:9090/validate; # 确保传递原始主机头 proxy_set_header Host $http_host; # Vouch Proxy 仅作用于请求头 proxy_pass_request_body off; proxy_set_header Content-Length ""; # 可选:添加 Vouch Proxy 返回的 X-Vouch-User 至请求 auth_request_set $auth_resp_x_vouch_user $upstream_http_x_vouch_user; # 可选:添加自定义声明(如 X-Vouch-IdP-Claims-*) # auth_request_set $auth_resp_x_vouch_idp_claims_groups $upstream_http_x_vouch_idp_claims_groups; # auth_request_set $auth_resp_x_vouch_idp_claims_given_name $upstream_http_x_vouch_idp_claims_given_name; # 可选:添加 X-Vouch-IdP-AccessToken 或 X-Vouch-IdP-IdToken # auth_request_set $auth_resp_x_vouch_idp_accesstoken $upstream_http_x_vouch_idp_accesstoken; # auth_request_set $auth_resp_x_vouch_idp_idtoken $upstream_http_x_vouch_idp_idtoken; # 这些返回值供 @error401 调用使用 auth_request_set $auth_resp_jwt $upstream_http_x_vouch_jwt; auth_request_set $auth_resp_err $upstream_http_x_vouch_err; auth_request_set $auth_resp_failcount $upstream_http_x_vouch_failcount; # Vouch Proxy 可运行在同一 Nginx 反向代理之后 # 可能需要符合 "upstream" 服务器命名 # proxy_pass http://vouch.yourdomain.com/validate; # proxy_set_header Host $http_host; } # 若 validate 返回 `401 未授权`,则将请求转发至 error401block error_page 401 = @error401; location @error401 { # 重定向至 Vouch Proxy 进行登录 return 302 https://vouch.yourdomain.com/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$auth_resp_jwt&error=$auth_resp_err; # 通常建议将重定向指向由同一 Nginx 配置保护的 HTTPS 下的 Vouch # 但为快速开始,可直接将用户转发至 Vouch 运行的端口 # return 302 http://vouch.yourdomain.com:9090/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$auth_resp_jwt&error=$auth_resp_err; } location / { # 将授权请求转发至受保护服务 protectedapp.yourdomain.com proxy_pass http://127.0.0.1:8080; # 可能需要按 https://github.com/vouch/vouch-proxy/issues/26#issuecomment-425215810 在该块中设置这些变量 # auth_request_set $auth_resp_x_vouch_user $upstream_http_x_vouch_user # auth_request_set $auth_resp_x_vouch_idp_claims_groups $upstream_http_x_vouch_idp_claims_groups; # auth_request_set $auth_resp_x_vouch_idp_claims_given_name $upstream_http_x_vouch_idp_claims_given_name; # 设置用户头(通常为邮箱) proxy_set_header X-Vouch-User $auth_resp_x_vouch_user; # 可选:传递自定义声明 # proxy_set_header X-Vouch-IdP-Claims-Groups $auth_resp_x_vouch_idp_claims_groups; # proxy_set_header X-Vouch-IdP-Claims-Given_Name $auth_resp_x_vouch_idp_claims_given_name; # 可选:传递访问令牌或 ID 令牌 # proxy_set_header X-Vouch-IdP-AccessToken $auth_resp_x_vouch_idp_accesstoken; # proxy_set_header X-Vouch-IdP-IdToken $auth_resp_x_vouch_idp_idtoken; } }
若 Vouch 配置在同一 Nginx 反向代理之后(https://github.com/vouch/vouch-proxy/issues/64#issuecomment-461085139%EF%BC%89%EF%BC%8C%E7%A1%AE%E4%BF%9D%E6%AD%A3%E7%A1%AE%E4%BC%A0%E9%80%92 Host 头,否则 JWT Cookie 无法正确设置到域中:
server { listen 443 ssl http2; server_name vouch.yourdomain.com; ssl_certificate /etc/letsencrypt/live/vouch.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/vouch.yourdomain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:9090; # 确保传递原始主机头 proxy_set_header Host $http_host; } }
更多 Nginx 配置示例可在 https://github.com/vouch/vouch-proxy/tree/master/examples 目录中找到。
以下是使用 Google OAuth 的最小化配置:
bashVOUCH_DOMAINS=yourdomain.com \ OAUTH_PROVIDER=google \ OAUTH_CLIENT_ID=1234 \ OAUTH_CLIENT_SECRET=secretsecret \ OAUTH_CALLBACK_URL=https://vouch.yourdomain.com/auth \ ./vouch-proxy
环境变量名称在 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example 中有详细说明。
所有多值列表必须用逗号分隔:VOUCH_DOMAINS="yourdomain.com,yourotherdomain.com"
变量 VOUCH_CONFIG 可用于指定配置文件的替代路径。VOUCH_ROOT 可用于设置 Vouch Proxy 查找支持文件的替代根目录。
所有 Vouch Proxy 配置项在 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example 中有详细说明。
欢迎帮助我们扩展此列表。
通过 Vouch Proxy,您可以请求各种 作用域(标准和自定义)以获取用户更多信息或访问提供商 API。Vouch Proxy 在成功认证后会向 user_info_url 发送请求,从提供商响应中提取所需 声明 并存储在 Vouch Cookie 中。
⚠️ 额外声明和令牌将添加到 VP Cookie 中,可能导致 Cookie 过大
VP Cookie 可能会被分割为多个 Cookie,但如果确实需要这些信息,则不可避免。大 Cookie 和头信息需要 Nginx 配置更大的缓冲区。详见 http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers 和 http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size%E3%80%82
在 Vouch Proxy 和 Nginx 中设置 作用域 和 声明
按常规配置 Vouch Proxy 以用于 Nginx 和您的 IdP(参见:安装与配置)
在 Vouch Proxy config.yml 的 oauth 部分设置必要的 作用域(示例配置)
config.yml 的 headers 部分设置 idtoken: X-Vouch-IdP-IdToken/validate 端点X-Vouch-IdP-IdToken 头config.yml 中 oauth 部分的 作用域 或重新配置 OAuth 提供商在 Vouch Proxy config.yml 的 header 部分设置必要的 声明
/validate 端点您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本,请访问 标签列表页面。
来自真实用户的反馈,见证轩辕镜像的优质服务