对比项	传统模式	飞网接入模式
网络连接策略	先连接网络 → 后认证	先认证身份 → 后连接网络
服务是否暴露公网	是	否
攻击面	Nginx 网关，业务系统	飞网连接器（需授权方能连入）
身份控制位置	应用层认证逻辑	网络接入前已完成身份控制
安全性	风险大，依赖应用自身防御	高，接入前强身份隔离
用户体验	登录表单认证	无需登录，身份自动注入

✅ 飞网模式通过“网络即身份”的理念，实现“看不见、连不上、打不穿”的访问控制体系，有效解决传统暴露服务面广、安全风险高的难题。

🚀 4.飞网 Nginx 认证连接器使用指南

4.1 体验飞网 Nginx 认证服务

在接入飞网测试团队网络之前，访问飞网单点登录演示项目（地址如下）：

https://demo2.demonet.gmzta.net/

此时由于尚未接入体验网络，访问将会失败，页面显示如下所示的认证失败信息：

飞网nginx网络认证演示网址

认证失败

注册飞网账号，并成功接入测试团队网络后，页面访问状态会发生变化，进入认证成功界面。如下图所示：

加入体验网络

飞网 Nginx 认证服务测试

4.2 安装飞网 Nginx 认证连接器

4.2.1 下载飞网 Nginx 认证连接器安装包。

注：需要在安装飞网后使用

根据您的操作系统类型和CPU架构选择并安装飞网 Nginx 认证连接程序文件：

🐧 Debian / Ubuntu 系统

wget -N https://pkgs.gmzta.com/deb/gmzta-nginx-connector-amd64.deb
sudo apt install ./gmzta-nginx-connector-amd64.deb

🧱 Red Hat / CentOS 系统

wget -N https://pkgs.gmzta.com/rpm/gmzta-nginx-connector-amd64.rpm
sudo yum install ./gmzta-nginx-connector-amd64.rpm

4.2.2. 配置Nginx，开启无密码身份验证

注：若未安装Nginx，请自行安装Nginx。

编辑Nginx配置文件，添加以下内容：

需自行配置后端应用地址


server {
    listen 80;
    server_name 127.0.0.1; # 监听本地地址

    error_log /var/log/nginx/error.log debug;
    access_log /var/log/nginx/access.log;

    # 认证请求转发到 socket 服务
    location = /auth {
        internal;

        proxy_pass http://unix:/var/run/gmzta-nginx-connector.sock;
        proxy_pass_request_body off;
        proxy_set_header Host $http_host;
        proxy_set_header Remote-Addr $remote_addr;
        proxy_set_header Remote-Port $remote_port;
        proxy_set_header Original-URI $request_uri;

        proxy_hide_header Content-Type;
        add_header Content-Type 'text/plain';

        limit_except GET HEAD {
            deny all;
        }
    }

   # 错误页：认证失败时跳转到 401 页面
    error_page 401 /401.html;

    # 配置 401 页面
    location = /401.html {
        root /usr/share/nginx/html;
        internal;  # 防止用户直接访问 401 页面
    }
    location / {
        auth_request /auth;
        auth_request_set $auth_user $upstream_http_gmzta_user;
        auth_request_set $auth_name $upstream_http_gmzta_name;
        auth_request_set $auth_login $upstream_http_gmzta_login;
        auth_request_set $auth_gmztanet $upstream_http_gmzta_gmztanet;
        auth_request_set $auth_profile_picture $upstream_http_gmzta_profile_picture;

        proxy_set_header X-Webauth-GmztaUser "$auth_user";
        proxy_set_header X-Webauth-GmztaName "$auth_name";
        proxy_set_header X-Webauth-GmztaLogin "$auth_login";
        proxy_set_header X-Webauth-GmztaNet "$auth_gmztanet";
        proxy_set_header X-Webauth-Gmzta-Profile-Picture "$auth_profile_picture";
        proxy_pass http://localhost:3002;  # 转发到后端应用

        # 展示 nginx 默认页面
        # root /usr/share/nginx/html;
        # index index.html;
        # 让 nginx 直接处理请求而不是转发
        # try_files $uri $uri/ =404;
        # default_type text/html; -->
    }
}

上述配置使用了Nginx的一个特性：基于子请求结果的身份认证。Nginx和Nginx Plus可以通过外部服务器或外部服务对网站的每个请求进行身份验证。为了执行身份验证，NGINX向外部服务器发出一个HTTP子请求，并在那里对该子请求进行身份验证。如果子请求返回一个2xx响应代码，表示身份验证成功则允许继续访问；如果子请求返回401或者403，表示身份验证失败则拒绝访问。这种类型的身份验证可以实现各种身份验证方案，例如多因素身份验证，或者实现LDAP或OAuth身份验证。
更多资料访问

4.2.3重启nginx服务。

nginx -s reload

4.2.4开启飞网nginx 认证连接器

// 开启服务
systemctl start gmzta.nginx-connector.socket
systemctl start gmzta.nginx-connector.service
// 配置开机自启
systemctl enable gmzta.nginx-connector.socket
systemctl enable gmzta.nginx-connector.service

4.3 docker 安装飞网 Nginx 认证连接器

4.3.1 准备nginx配置文件

参考4.1安装飞网-nginx-认证连接器

4.3.2 拉取镜像

docker pull registry.cn-beijing.aliyuncs.com/gmzta/gmzta-nginx-connector:latest

4.3.2 启动容器

docker run -d \
  --name gmzta-nginx-connector \
  --hostname gmzta-nginx-connector \
  -p 80:80 \
  -e GM_TOKEN=gmzta-authkey-1234567890abcd \
  -e GM_CONFIG_DIR=/var/lib/gmzta \
  -e GM_TUN=false \
  -v $(pwd)/gmzta/conf:/var/lib/gmzta \
  -v $(pwd)/default.conf:/etc/nginx/conf.d/default.conf \
  --restart unless-stopped \
  registry.cn-beijing.aliyuncs.com/gmzta/gmzta-nginx-connector:latest

贡献者

herotheo lsleishu lizhengaas