第24章 常用 API 路由指南:Pangolin 核心组件创建与标识符解析
常用 API 路由 针对最常见操作和流程的 API 路由与模式
本指南中的所有路由都需要 API key。创建和使用 API key(Authorization 请求头中的 Bearer token)请参见 Integration API。许多路由的路径中包含 organization ID,获取方式见 Organization ID。
本指南是通过 API 创建 Pangolin 核心组件(site、resource、target)的极简教程。它并不全面——为简洁起见省略了一些内容——但这里展示的一切都可用,并体现了 API 其他地方使用的模式。要完整了解所有端点(get、update、delete、list 等),请使用 Swagger 文档。
符合 OpenAPI 规范的文档可在 https://api.pangolin.net/v1/openapi.json 和 https://api.pangolin.net/v1/openapi.yaml 获取。
什么是标识符?
在 Pangolin 应用中,site、公开资源、私有资源和 client 都有一个 Identifier。在 API 中,这个值叫 niceId。
标识符是人类可读的值,在组织内唯一。当你想要比数字 ID 更稳定、更好记的东西时可以用它。例如,某个 site 的数字 siteId 是 8723,niceId 是 warehouse-west。
在哪里找到标识符
在控制台中,你可以在以下两个位置之一找到实体的标识符:
URL slug — 打开 site、resource 等实体页面时,标识符会出现在页面 URL 中。 General settings(通用设置)— 打开实体,进入其通用设置,找到 Identifier 字段。你可以在这里修改标识符。
标识符对自动化尤其有用:
在 Blueprints 中,resource 和 site 的 key 就充当稳定的标识符。target 可以通过标识符引用 site,例如 site: warehouse-west。 在 API 中,如果对象支持标识符,响应会同时包含数字 ID 和 niceId。部分路由还支持通过 niceId 查找对象,例如 site 的 GET /org/{orgId}/site/{niceId}。
当端点要求 siteId、resourceId 或 siteResourceId 时,用数字 ID;当端点或 blueprint 字段要求标识符时,用 niceId。
创建 site
本节假设你在创建 Pangolin Site。所有 Site 端点见 Site API (Swagger)。
PUT /org/{orgId}/site
Path
orgId (string) — organization ID
Body (Newt) 字段 | 类型 | 必填 | 说明 name | string | 是 | site 的显示名称 type | string | 是 | 使用 "newt" niceId | string | 否 | site 的标识符,组织内必须唯一,缺省时自动生成
如果不提供,Pangolin 会自动生成 Newt 凭据(newtId 和 secret)以及 site 地址。secret 只在创建响应中出现,请务必保存。
示例响应 { "data": { "siteId": 8723, "niceId": "quiet-lerista-labialis", "name": "My Site", "type": "newt", "online": false, "address": "100.90.128.0/24", "newtId": "se897rmyjvamy5q", "secret": "ystsahnvqetgx1fhn2udylq0zqgv611zbfp6ya3jvfrprn7q" }, "success": true, "error": false, "message": "Site created successfully", "status": 201 }
高级选项:pick-site-defaults
当你想生成一些模板值并自行控制 site 创建时使用。
GET /org/{orgId}/pick-site-defaults
返回要传给创建 site 端点的值。响应还包含 exit node 相关字段(exitNodeId、subnet、endpoint 等)。Newt site 不会用到它们,因为 Newt 在连接时会自行选择 exit node。
Path
orgId (string) — organization ID
示例响应 { "data": { "newtId": "jwhk5154mfmos0s", "newtSecret": "8afipi4i79jjbsxjqpkgc0xe2ge143s54oi64mw5567mxgr8", "clientAddress": "100.90.128.0" }, "success": true, "error": false, "message": "Site defaults chosen successfully", "status": 200 }
创建 site
PUT /org/{orgId}/site
Path
orgId (string) — organization ID
Body (Newt) 字段 | 类型 | 必填 | 说明 name | string | 是 | site 的显示名称 type | string | 是 | 使用 "newt" address | string | 否 | 来自 pick-site-defaults 的 clientAddress。必须是组织子网内未被其他 site 或 client 使用的 IP。 newtId | string | 否 | 来自 pick-site-defaults 的 newtId secret | string | 否 | 来自 pick-site-defaults 的 newtSecret niceId | string | 否 | site 的标识符,组织内必须唯一
示例响应 { "data": { "siteId": 8723, "niceId": "quiet-lerista-labialis", "name": "My Site", "type": "newt", "online": false, "address": "100.90.128.0/24", "newtId": "se897rmyjvamy5q", "secret": "ystsahnvqetgx1fhn2udylq0zqgv611zbfp6ya3jvfrprn7q" }, "success": true, "error": false, "message": "Site created successfully", "status": 201 }
创建公开 HTTP 资源
创建资源前需要先有 domain ID。先列出组织的域名,然后用选定的 domain 创建资源。所有公开资源端点见 Public Resource API (Swagger)。
列出域名:调用 list-domains 端点获取可用域名及其 domainId。 创建资源:调用 create-resource 端点,传入 mode: "http" 和第一步的 domainId。 为资源添加 target:对每个要承接该资源流量的后端(site + ip:port),调用 create-target 端点。
列出域名
GET /org/{orgId}/domains
返回组织的所有域名。创建资源时使用某个域名的 domainId。
Path
orgId (string) — organization ID
Query(可选) 参数 | 类型 | 默认值 | 说明 limit | number | 1000 | 最多返回的域名数量 offset | number | 0 | 分页偏移量
示例响应 { "data": { "domains": [ { "domainId": "pg3i1k4lhibhl3i", "baseDomain": "pangolin.net", "verified": true, "type": "ns" }, { "domainId": "q1ngj5341k7oydo", "baseDomain": "bitwarden.pangolin.net", "verified": true, "type": "cname" } ], "pagination": { "total": 2, "limit": 1000, "offset": 0 } }, "success": true, "error": false, "message": "Domains retrieved successfully", "status": 200 }
创建公开 HTTP 资源
PUT /org/{orgId}/public-resource
Path
orgId (string) — organization ID
Body(HTTP 资源) 字段 | 类型 | 必填 | 说明 name | string | 是 | 资源显示名称(1–255 字符) mode | string | 是 | 公开 HTTP 资源使用 "http" domainId | string | 是 | 来自 list-domains subdomain | string | null | 否 | 见下文
旧版集成发送的是 http: true 和 protocol: "tcp" 而非 mode。API 仍接受这些字段,但已弃用,请改用 mode。
子域名与域名类型
域名分三种类型:ns | cname | wildcard。 wildcard 仅自托管版 Pangolin 支持,Pangolin Cloud 只支持 ns 和 cname。
ns — 可以直接使用基础域名(subdomain 设为 null),也可以设置子域名(如 my-app → my-app.digpangolin.io)。 cname — 只能使用基础域名,subdomain 设为 null(域名的 baseDomain 即为 FQDN)。 wildcard — 子域名行为与 ns 相同(仅自托管版)。
subdomain 会与 domainId 对应的基础域名组合成 FQDN。只用基础域名时,省略 subdomain 或传 null。
示例请求 { "name": "My Resource", "mode": "http", "subdomain": "my-subdomain", "domainId": "pg3i1k4lhibhl3i" }
示例响应 { "data": { "resourceId": 9942, "niceId": "decent-louisiana-waterthrush", "name": "My Resource", "subdomain": "my-subdomain", "fullDomain": "my-subdomain.pangolin.net", "domainId": "pg3i1k4lhibhl3i" }, "success": true, "error": false, "message": "Http resource created successfully", "status": 201 }
为资源添加 target
PUT /public-resource/{resourceId}/target
为资源添加 target(后端)。使用 create-resource 响应中的数字 resourceId。target 是承接该资源流量的 site 和地址(ip + 端口)。所有 target 端点见 Resource Target API (Swagger)。
Path
resourceId (number) — 来自 create-resource 响应(如 9942)
Body 字段 | 类型 | 必填 | 说明 siteId | number | 是 | 承载后端的 site(来自 create-site 或 site 列表) ip | string | 是 | 后端 IP 或主机名 port | number | 是 | 后端端口 method | string | 是(HTTP) | Pangolin 访问后端使用的协议:"http"、"https" 或 "h2c"。HTTP 资源必填;没有 method 的 HTTP target 会被 Pangolin 跳过。
示例请求 { "ip": "localhost", "port": 8080, "method": "http", "siteId": 8723 }
示例响应 { "data": { "targetId": 11280, "resourceId": 9942, "siteId": 8723, "ip": "localhost", "method": "http", "port": 8080 }, "success": true, "error": false, "message": "Target created successfully", "status": 201 }
创建私有资源
前提是已有 site。更多端点见 Private Resource API (Swagger)。
创建私有资源
PUT /org/{orgId}/private-resource
Path
orgId (string) — organization ID
Body 字段 | 类型 | 必填 | 说明 name | string | 是 | 显示名称(1–255 字符) siteIds | number[] | 是 | 可访问该资源的 site(来自 create-site 或 site 列表) mode | string | 是 | "host" 或 "cidr"。本指南涵盖这两种;http、ssh、inference 和 gateway 见 Swagger。 destination | string | 是 | host 模式:IPv4 地址或主机名(如 localhost)。cidr 模式:CIDR(如 10.0.0.0/24)。 alias | string | host+domain 时 | 别名,形式为完全限定域名(如 private-resource.internal)。支持通配符(如 *.example.internal)。destination 为主机名时必填,为 IP 时可选。组织内必须唯一。 roleIds | number[] | 是 | 可访问的角色 ID,无则传 []。 userIds | string[] | 是 | 可访问的用户 ID,无则传 []。 clientIds | number[] | 是 | 可访问的机器 client ID,无则传 []。 tcpPortRangeString | string | 否 | 见下文,默认 "*"。 udpPortRangeString | string | 否 | 见下文,默认 "*"。 disableIcmp | boolean | 否 | 默认 false niceId | string | 否 | 资源的标识符,缺省时自动生成
旧版 siteId(单个数字)字段仍可用,会合并进 siteIds,但已弃用。
TCP/UDP 端口范围字符串:控制私有资源允许的端口。
"*" — 允许所有端口(TCP 场景下想完全访问主机时常用)。 ""(空字符串)— 不允许任何端口。不需要该协议时使用(例如只用 TCP 时 udpPortRangeString: "")。 具体端口或范围 — 逗号分隔列表:单端口(如 "80,443")或范围(如 "8000-9000")。例如 "80,443,8080-8090" 允许 80、443 和 8080–8090。
tcpPortRangeString 和 udpPortRangeString 可以独立设置(如 TCP 全开、UDP 全关,反之亦然)。 组织 Admin 角色始终拥有访问权限,你指定的角色、用户和 client 是在其基础上额外授权。
示例请求 { "name": "My Private Resource", "siteIds": [8723], "mode": "host", "destination": "localhost", "alias": "private-resource.internal", "tcpPortRangeString": "*", "udpPortRangeString": "", "disableIcmp": false, "roleIds": [], "userIds": [], "clientIds": [] }
示例响应 { "data": { "siteResourceId": 1165, "networkId": 412, "niceId": "unsung-round-tailed-ground-squirrel", "name": "My Private Resource", "mode": "host", "destination": "localhost", "alias": "private-resource.internal", "tcpPortRangeString": "*", "udpPortRangeString": "", "disableIcmp": false }, "success": true, "error": false, "message": "Site resource created successfully", "status": 201 }
为资源分配用户和角色(公开或私有)
你可以通过添加角色或用户来授予对公开资源或私有资源的访问权限。先列出组织中的角色和用户获取 ID,再调用添加端点。Admin 角色不能通过这些端点分配。
获取角色和用户 ID
GET /org/{orgId}/roles 返回 data.roles,即组织中的角色。添加角色到资源时使用角色的 roleId(数字)。可选查询参数:page(默认 1)、pageSize(默认 20)、query(按名称过滤)。
GET /org/{orgId}/users 返回 data.users,即组织中的用户。添加用户到资源时使用用户的 id(字符串)作为 userId。可选查询参数:page(默认 1)、pageSize(默认 20)、query(搜索)。
公开资源
POST /public-resource/{resourceId}/roles/add — Path: resourceId(数字,来自 create public-resource)。Body: { "roleId": number }。不允许 Admin 角色。 POST /public-resource/{resourceId}/users/add — Path: resourceId(数字)。Body: { "userId": string }。
两者都返回 { "data": {}, "success": true, "error": false, "message": "...", "status": 201 }。
私有资源
POST /private-resource/{siteResourceId}/roles/add — Path: siteResourceId(数字,来自 create private-resource)。Body: { "roleId": number }。不允许 Admin 角色。 POST /private-resource/{siteResourceId}/users/add — Path: siteResourceId(数字)。Body: { "userId": string }。
响应格式与上文相同。角色必须属于私有资源所在的组织。更多端点(list/remove)见 Public Resource API 和 Private Resource API。
此页面有帮助吗?