Newt Blueprint Generator

Name: Newt Blueprint Generator
Author: rknall

github.com/rknall云与 DevOps86291 次安装53 周前更新

代码仓库

关于 Newt Blueprint Generator

用于创建、验证和管理 Pangolin Newt blueprint 配置的技能，适合配置代理资源的用户。支持独立 YAML 和 Docker Labels，并指导客户端资源、认证及协议约束校验。

主要功能

01生成 YAML blueprint
02配置 Docker Labels
03定义代理和客户端资源
04设置 HTTP 资源认证
05校验协议和资源约束

适用场景

01创建 HTTP、TCP 或 UDP 代理资源
02配置 Olm 客户端资源
03转换 blueprint 配置格式
04排查 blueprint 校验错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rknall/claude-skills --skill newt-blueprint-generator

安装后在 Claude Code 中输入/newt-blueprint-generator确认已加载。

附带文件README.mdvalidation-reference.md

详细介绍

Newt Blueprint 生成器

为创建、验证和管理 Pangolin Newt blueprint 配置提供专家级帮助。

何时使用此技能

在以下情况下应触发此技能：

创建 Pangolin blueprint 配置
为 Newt 生成 YAML 配置文件
创建带有 Pangolin 标签的 Docker Compose 文件
配置代理资源（HTTP、TCP、UDP）
为 Olm 设置客户端资源
配置身份验证（SSO、基本身份验证、PIN 码、密码）
验证 blueprint 配置
排查 blueprint 验证错误
在 YAML 和 Docker 标签格式之间转换

概述

Pangolin Blueprints 是声明式配置，可让你以结构化格式定义资源及其设置。它们支持两种格式：

YAML 配置文件：独立配置文件
Docker 标签：嵌入在 Docker Compose 文件中的配置

Blueprint 格式

YAML 配置格式

可通过以下方式应用 YAML 配置：

Newt CLI：传入 --blueprint-file /path/to/blueprint.yaml
API：向 /org/{orgId}/blueprint 发送 POST 请求，附带经过 base64 编码的 JSON 请求体

Newt 用法示例：

newt --blueprint-file /path/to/blueprint.yaml <other-args>

Docker 标签格式

对于容器化应用，可以使用带有 pangolin. 前缀的 Docker 标签定义 blueprints。

启用 Docker 套接字访问：

newt --docker-socket /var/run/docker.sock <other-args>

或使用环境变量：

DOCKER_SOCKET=/var/run/docker.sock

资源类型

代理资源

代理资源通过 Pangolin 暴露 HTTP、TCP 或 UDP 服务。

HTTP 代理资源示例

proxy-resources:
  resource-nice-id-uno:
    name: this is a http resource
    protocol: http
    full-domain: uno.example.com
    host-header: example.com
    tls-server-name: example.com
    headers:
      - name: X-Example-Header
        value: example-value
      - name: X-Another-Header
        value: another-value
    rules:
      - action: allow
        match: ip
        value: 1.1.1.1
      - action: deny
        match: cidr
        value: 2.2.2.2/32
      - action: pass
        match: path
        value: /admin
    targets:
      - site: lively-yosemite-toad
        hostname: localhost
        method: http
        port: 8000
      - site: slim-alpine-chipmunk
        hostname: localhost
        path: /admin
        path-match: exact
        method: https
        port: 8001

TCP/UDP 代理资源示例

proxy-resources:
  resource-nice-id-dos:
    name: this is a raw resource
    protocol: tcp
    proxy-port: 3000
    targets:
      - site: lively-yosemite-toad
        hostname: localhost
        port: 3000

仅含目标的资源

仅包含目标配置的简化资源：

proxy-resources:
  additional-targets:
    targets:
      - site: another-site
        hostname: backend-server
        method: https
        port: 8443
      - site: another-site
        hostname: backup-server
        method: http
        port: 8080

注意：使用仅含目标的资源时，不需要 name 和 protocol 字段。

客户端资源

客户端资源定义可通过 Olm 客户端访问的代理资源（SSH、RDP）：

client-resources:
  client-resource-nice-id-uno:
    name: this is my resource
    protocol: tcp
    proxy-port: 3001
    hostname: localhost
    internal-port: 3000
    site: lively-yosemite-toad

身份验证配置

默认情况下关闭身份验证。可通过在 auth 部分添加字段来启用。

注意：身份验证仅允许用于 HTTP 资源，不适用于 TCP/UDP。

proxy-resources:
  secure-resource:
    name: Secured Resource
    protocol: http
    full-domain: secure.example.com
    auth:
      pincode: 123456
      password: your-secure-password
      basic-auth:
        user: asdfa
        password: sadf
      sso-enabled: true
      sso-roles:
        - Member
        - Admin
      sso-users:
        - [email protected]
      whitelist-users:
        - [email protected]

Docker 标签格式

完整的 Docker Compose 示例

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - NEWT_ID=h1rbsgku89wf9z3
      - NEWT_SECRET=z7g54mbcwkglpx1aau9gb8mzcccoof2fdbs97keoakg2pp5z
      - DOCKER_SOCKET=/var/run/docker.sock

  nginx1:
    image: nginxdemos/hello
    container_name: nginx1
    labels:
      # Proxy Resource Configuration
      - pangolin.proxy-resources.nginx.name=nginx
      - pangolin.proxy-resources.nginx.full-domain=nginx.fosrl.io
      - pangolin.proxy-resources.nginx.protocol=http
      - pangolin.proxy-resources.nginx.headers[0].name=X-Example-Header
      - pangolin.proxy-resources.nginx.headers[0].value=example-value
      # Target Configuration - port and hostname auto-detected
      - pangolin.proxy-resources.nginx.targets[0].method=http
      - pangolin.proxy-resources.nginx.targets[0].path=/path
      - pangolin.proxy-resources.nginx.targets[0].path-match=prefix

  nginx2:
    image: nginxdemos/hello
    container_name: nginx2
    labels:
      # Additional target with explicit hostname and port
      - pangolin.proxy-resources.nginx.targets[1].method=http
      - pangolin.proxy-resources.nginx.targets[1].hostname=nginx2
      - pangolin.proxy-resources.nginx.targets[1].port=80

networks:
  default:
    name: pangolin_default

Docker 标签注意事项

自动发现：未定义主机名和内部端口时，Pangolin 会根据容器配置自动检测
站点分配：未指定站点时，资源会分配给发现该资源的 Newt 站点
配置合并：跨容器的配置会合并，以构成完整的资源定义

配置属性参考

代理资源属性

属性	类型	必填	描述	限制
`name`	字符串	条件必填	易读的名称	除仅含目标的资源外均必填
`protocol`	字符串	条件必填	协议类型（`http`、`tcp`、`udp`）	除仅含目标的资源外均必填
`full-domain`	字符串	仅限 HTTP	完整域名	HTTP 必填，且必须唯一
`proxy-port`	数字	仅限 TCP/UDP	原始 TCP/UDP 的端口	TCP/UDP 必填，范围为 1-65535，且必须唯一
`ssl`	布尔值	否	启用 SSL/TLS	-
`enabled`	布尔值	否	是否启用资源	默认为 `true`
`host-header`	字符串	否	自定义 Host 标头	-
`tls-server-name`	字符串	否	TLS 的 SNI 名称	-
`headers`	数组	否	自定义标头	每项都需要 `name` 和 `value`（至少 1 个字符）
`rules`	数组	否	访问控制规则	请参见规则部分
`auth`	对象	仅限 HTTP	身份验证配置	请参见身份验证部分
`targets`	数组	是	目标端点	请参见目标部分

目标配置属性

属性	类型	必填	描述	约束
`site`	string	否	站点标识符	-
`hostname`	string	是	目标主机名或 IP	-
`port`	number	是	目标端口	1-65535
`method`	string	仅限 HTTP	协议方法（`http`、`https`、`h2c`）	HTTP 必填
`enabled`	boolean	否	是否启用目标	默认为 `true`
`internal-port`	number	否	内部端口映射	1-65535
`path`	string	仅限 HTTP	路径前缀、精确路径或正则表达式	-
`path-match`	string	仅限 HTTP	路径匹配类型（`prefix`、`exact`、`regex`）	-

身份验证属性

TCP/UDP 资源不允许使用。

属性	类型	必填	描述	约束
`pincode`	number	否	6 位 PIN 码	必须恰好为 6 位数字
`password`	string	否	访问密码	-
`basic-auth`	object	否	基本身份验证配置	需要 `user` 和 `password`
`sso-enabled`	boolean	否	启用 SSO	默认为 `false`
`sso-roles`	array	否	允许的 SSO 角色	不能包含 "Admin" 角色
`sso-users`	array	否	允许的 SSO 用户邮箱	必须是有效邮箱
`whitelist-users`	array	否	白名单用户邮箱	必须是有效邮箱

规则配置属性

属性	类型	必填	描述	约束
`action`	string	是	规则操作（`allow`、`deny`、`pass`）	-
`match`	string	是	匹配类型（`cidr`、`path`、`ip`、`country`）	-
`value`	string	是	要匹配的值	格式取决于匹配类型

客户端资源属性

属性	类型	必填	描述	约束
`name`	string	是	易于识别的名称	2-100 个字符
`protocol`	string	是	协议类型（`tcp`、`udp`）	-
`proxy-port`	number	是	客户端可访问的端口	1-65535，必须唯一
`hostname`	string	是	目标主机名或 IP	1-255 个字符
`internal-port`	number	是	目标系统上的端口	1-65535
`site`	string	否	站点标识符	2-100 个字符
`enabled`	boolean	否	是否启用资源	默认为 `true`

验证规则和约束

资源级验证

仅含目标的资源：资源可以只包含 targets 字段，此时 name 和 protocol 为可选项
特定协议的要求：
- HTTP 协议：必须包含 full-domain，且所有目标都必须包含 method 字段
- TCP/UDP 协议：必须包含 proxy-port，且目标不得包含 method 字段
- TCP/UDP 协议：不能包含 auth 配置
端口唯一性：
- proxy-resources 中的 proxy-port 值必须唯一
- client-resources 中的 proxy-port 值必须唯一
- 不会对代理资源和客户端资源进行交叉验证
域名唯一性：所有代理资源中的 full-domain 值必须唯一
目标方法要求：当协议为 http 时，所有非空目标都必须指定 method

常见验证错误

"Admin role cannot be included in sso-roles"

Admin 角色为保留角色，不能包含在 sso-roles 数组中。

解决方案：从 sso-roles 数组中移除 "Admin"。

"Duplicate 'full-domain' values found"

所有代理资源中的 full-domain 都必须唯一。

解决方案：为多个资源使用不同的子域名或路径。

"Duplicate 'proxy-port' values found"

proxy-port 中的端口号在各自的资源类型中必须唯一。

解决方案：分别为 proxy-resources 和 client-resources 分配唯一的端口号。

“当协议为 'http' 时，所有目标都必须包含 'method' 字段”

HTTP 代理资源中的所有目标都必须指定连接方法。

解决方案：为所有目标添加 method: http、method: https 或 method: h2c。

“当协议为 'tcp' 或 'udp' 时，目标不得包含 'method' 字段”

TCP 和 UDP 目标不应包含 method 字段。

解决方案：从 TCP/UDP 资源目标中移除 method 字段。

“当协议为 'tcp' 或 'udp' 时，不得提供 'auth'”

仅 HTTP 资源支持身份验证。

解决方案：从 TCP/UDP 资源中移除 auth 部分。

“资源必须仅包含 targets，或同时包含 'name' 和 'protocol' 字段”

资源必须仅包含 targets，或使用完整的资源定义。

解决方案：仅提供 targets 字段，或同时包含 name 和 protocol 字段。

生成 Blueprint 的工作流

当用户请求 Pangolin Newt blueprint 配置时：

收集需求：
- 资源类型（代理或客户端）
- 协议（HTTP、TCP、UDP）
- 域名或端口要求
- 目标端点（主机名、端口、站点）
- 身份验证需求（如果是 HTTP）
- 访问控制规则（如有）
- 格式偏好（YAML 或 Docker Labels）
选择格式：
- 独立配置或通过 API 部署时使用 YAML
- 容器化应用使用 Docker Labels
验证配置：
- 确保满足特定协议的要求
- 检查 full-domain（HTTP）或 proxy-port（TCP/UDP）是否唯一
- 确认身份验证仅用于 HTTP 资源
- 确认所有 HTTP 目标都包含 method 字段
- 确保 TCP/UDP 目标不包含 method 字段
生成配置：
- 创建结构清晰的 YAML 或 Docker Compose 文件
- 添加有用的注释，解释各个部分
- 遵循命名约定（资源 ID 使用 kebab-case）
提供使用说明：
- 说明如何应用配置（Newt CLI 或 API）
- 记录所需的环境变量
- 在适用时提供验证命令

最佳实践

资源 ID：使用描述性 kebab-case 标识符（例如，web-app-prod、database-backup）
目标组织：将相关目标归入同一个资源 ID
安全优先：为敏感的 HTTP 资源启用身份验证
端口管理：记录端口分配，避免冲突
站点分配：在多站点部署中明确指定 site
路径匹配：使用 prefix 进行广泛匹配，使用 exact 匹配特定端点
标头：根据后端要求添加自定义标头（例如，X-Forwarded-* 标头）
规则：按从最具体到最宽泛的顺序排列规则
验证：部署前务必验证配置
文档：在 YAML 或 Docker Compose 文件中添加注释，解释不明显的选择

资源

API 文档：https://api.pangolin.net/v1/docs/#/Organization/put_org__orgId__blueprint
Python 示例：https://github.com/fosrl/pangolin/blob/dev/blueprint.py
官方文档：https://docs.pangolin.net/manage/blueprints

示例用例

用例 1：简单的 Web 应用

需求：通过 HTTPS 在 app.example.com 上公开运行于 localhost:8080 的 Web 应用

proxy-resources:
  web-app:
    name: Web Application
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: https

用例 2：TCP 数据库访问

需求：公开端口 5432 上的 PostgreSQL 数据库

proxy-resources:
  postgres-db:
    name: PostgreSQL Database
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432

用例 3：多目标负载均衡 HTTP 服务

需求：同一域名对应多个后端服务器

proxy-resources:
  api-service:
    name: API Service
    protocol: http
    full-domain: api.example.com
    targets:
      - site: site-01
        hostname: backend-01
        port: 8080
        method: http
      - site: site-02
        hostname: backend-02
        port: 8080
        method: http

用例 4：使用 SSO 的安全资源

需求：带有 SSO 身份验证的 Web 应用

proxy-resources:
  secure-app:
    name: Secure Application
    protocol: http
    full-domain: secure.example.com
    auth:
      sso-enabled: true
      sso-roles:
        - Member
        - Developer
      sso-users:
        - [email protected]
    targets:
      - hostname: localhost
        port: 3000
        method: https

沟通风格

生成蓝图时：

如果需求不明确，请提出澄清问题
用通俗易懂的语言解释验证错误
提供完整且可运行的示例
为复杂配置添加注释
主动建议安全最佳实践
适用时，同时提供 YAML 和 Docker Labels 格式

支持 Markdown

登录后评论

基本信息

作者: rknall
仓库: rknall/claude-skills
分类: 云与 DevOps
安装次数: 291
GitHub Stars: 86

报告问题