🔗 OpenResty Edge 安装常见问题

🔗 系统要求与架构

🔗 OpenResty Edge 包含哪些主要组件？它们各自的作用是什么？

OpenResty Edge 主要包含三个核心组件：Edge Admin （管理控制台）、Edge Log Server（日志和指标服务器）和 Edge Node（网关节点）。此外还有两个数据存储组件：Edge Admin Database 和 Edge Log Server Database。

🔗 安装 OpenResty Edge 需要什么样的硬件配置？

正式环境至少需要三台机器，分别安装 Edge Admin + Admin DB、Log Server + Log Server DB 和 Edge Node。对于 10 个节点以内的集群，Edge Admin 和 Log Server 推荐至少 4 核 16G 内存 200G SSD，Edge Node 根据业务量而定，一般 1 核心配 2G 内存。

🔗 我的网络环境有防火墙限制，需要开放哪些端口和域名？

需要将 openresty.com 、openresty.org 、pkg.openresty.com 、api.openresty.com 的 443 端口加入白名单。各组件间也需要开放特定端口：Edge Admin 需要开放 443 和 12345 端口，Log Server 需要开放 12346 和 8089 端口。

🔗 安装过程

🔗 如何获取 OpenResty Edge 的安装包？

可以从 OpenResty 的下载中心 (https://openresty.com.cn/cn/dashboard/downloads) 获取在线安装包所需的配置包 (openresty-edge-VERSION.tar.gz) 和完整的离线安装包 (openresty-edge-bundle-VERSION.tar.gz) 。

🔗 安装完成后如何获取 Edge Admin 管理界面的登录账号和密码？

可以使用安装器的“Get Default Info”功能获取默认登录信息，或者联系技术支持重置密码。

🔗 安装完成后如何验证各组件是否正常工作？

可以通过 systemctl status 命令检查各服务状态，例如 sudo systemctl status oredge-admin，也可以查看各组件的日志目录，如 /usr/local/oredge-admin/logs 中是否有异常信息。

🔗 配置与高可用

🔗 如何提高 Edge Admin 和 Log Server 的可用性？

可以配置两份 Edge Admin 服务为双主模式，或部署多个 Log Server 实例。Edge Admin 需要修改 config.ini 中的 clone_admin 配置，Edge Node 需要配置 admin 段下的 host2 字段。Log Server 多实例需要在 Edge Admin 和 Edge Node 的配置中添加多个 endpoints。

🔗 如何保障数据安全？有哪些数据备份方案？

建议定期备份数据库，可以参考文档中的数据库备份章节。也可以搭建数据库集群，实现主从自动切换，提高数据库可用性。

🔗 安装后如何更新 Edge Admin 的 SSL 证书？

可以手动替换 /usr/local/oredge-admin/conf/ssl/ssl.crt 和 /usr/local/oredge-admin/conf/ssl/ssl.key 文件，或者在安装时通过 -s 和 -k 参数指定证书路径。 另外也可以使用 Edge Node 来代理 Edge Admin 的流量，为 Edge Admin 签发 SSL 证书。

🔗 故障排查

🔗 Edge Node 安装后显示“not yet approved”错误怎么办？

这是正常现象，表示 Edge Node 已成功连接 Edge Admin，需要在 Edge Admin 管理后台中批准该节点加入。可以参考网关集群文档进行操作。

🔗 OpenResty Edge™ SDK 客户常见问题

🔗 使用 SDK 时，最关键的认证信息（地址、端口、用户名、密码）从哪里获取

这些信息与您登录 Edge Admin Web 控制台的信息完全一致。Edge2Client 初始化所需的参数即是您后台的访问地址和登录凭证。如果您的 Admin 使用了非标准的 HTTPS 端口，请务必在地址中明确指定。

🔗 我的开发环境使用自签名证书，SDK 连接时报 SSL 错误，如何处理

这是非常常见的场景。您只需在调用 client.login() 前，执行 client.set_ssl_verify(False) 即可跳过证书验证。但在生产环境，强烈建议配置由权威 CA 签发的有效证书以确保安全。

🔗 我调用 API 修改了配置，为何没生效？正确的发布流程是怎样的

SDK 的所有配置变更都是事务性的，不会自动发布。这是一种安全设计，防止误操作影响线上服务。正确的流程是“修改 -> 发布 -> 验证”：

1. 修改：调用 new_rule(), put_app() 等接口执行变更。
2. 发布：调用 client.new_release() 将所有待定变更创建一个新版本并使其生效。
3. 验证：（可选但推荐）调用 client.sync_status() 检查配置是否已同步到所有节点。

🔗 使用 SDK 进行自动化操作（如批量更新规则、IP 名单）的最佳实践是什么？

1. 幂等性: 在执行创建操作前，先查询目标是否存在，避免重复创建。在执行更新时，确保脚本可重复运行。
2. 健壮性：在所有 API 调用外层都使用 try...except 捕获异常，并记录详细日志。
3. 性能考量：对于大规模批量操作（如一次更新上千个 IP） ，建议将数据分批处理，并在批次间加入短暂延时（如 1 秒），避免因请求频率过高而触发 Admin 的保护机制。

🔗 如何将 SDK 集成到我的 CI/CD 流水线（如 Jenkins, GitLab CI）中，实现配置即代码（Configuration as Code）？

这是 SDK 最有价值的应用场景。通常的做法是：

1. 代码化配置：将您的 Edge 应用配置（如上游、规则等）用特定格式（如 YAML, JSON）存储在代码仓库中。
2. 编写同步脚本：开发一个 Python 脚本，该脚本读取代码化的配置文件，并调用 SDK 接口，将配置应用到 Edge Admin 中。
3. 集成到 CI/CD：在您的 CI/CD 流水线中增加一个阶段（Stage），当配置代码发生变更时，自动触发该 Python 脚本，完成对 Edge 的配置变更和发布。
4. 凭证管理：将登录 Edge Admin 的高权限密码存放在 CI/CD 系统的密钥管理工具中，并通过安全的方式传递给脚本，避免明文存储。

🔗 OpenResty Edge 动态指标常见问题 (FAQ)

🔗 “动态指标”功能的核心价值是什么？什么场景下我应该使用它？

它的核心价值是提供标准仪表盘无法满足的、深度定制的业务和安全洞察力。当您遇到以下场景时，就应该使用它：

• 追踪特定业务指标：例如，统计 VIP 用户的请求数、某个新上线活动的 API 调用成功率、不同安卓版本的请求分布等。
• 进行精细化安全分析：例如，找出攻击某个特定 URI 最多的 Top 10 IP 地址，或统计被 WAF 拦截的请求中，来自某个特定国家的比例。
• 实现自定义的性能监控：例如，计算某个上游服务的 P99 响应延迟，而非仅仅是平均值。

🔗 在写查询前，我如何知道都能用哪些数据表和字段？有数据字典吗？

这是最关键的第一步。您可以依赖的数据源主要是 reqs （请求日志）和 waf_hits （WAF 日志）这两个虚拟表。要知道它们包含哪些确切的可用字段（例如 client_ip, status, uri, resp_header('Content-Type') 等），最权威的方式是查阅 OpenResty Edge 官方文档中关于动态指标章节。

🔗 我想统计一个业务指标，比如“根据 JWT 里的 user_id 字段，统计请求量最大的 Top 10 用户”，能做到吗？

可以，这正是动态指标的强大之处。假设您的 user_id 在名为 X-Jwt-Claim-User-Id 的请求头中，查询可以这样写：

-- 假设user_id在请求头'X-Jwt-Claim-User-Id'中
SELECT ngx_var('http_x_jwt_claim_user_id') as user_id, count(*) as count
FROM reqs
WHERE ngx_var('http_x_jwt_claim_user_id') != ''
GROUP BY user_id
ORDER BY count DESC
LIMIT 10;

关键在于利用 ngx_var() 函数来获取自定义请求头（http_ 前缀）或其他 Nginx 变量，从而将业务逻辑与日志数据关联起来。

🔗 动态指标查询是在哪里执行的？会不会影响线上网关的性能？

这是一个非常重要的安全问题。动态指标的查询是在 Edge Log Server（日志服务器）上执行的，它处理的是从网关节点旁路采集的日志数据。因此，无论您的查询多复杂，都不会对处理实时业务流量的 Edge Node（网关节点）造成任何性能影响。您可以放心地使用这一功能进行复杂的数据分析。

🔗 OpenResty Edge Edgelang 常见问题

🔗 我应该在什么场景下使用 Edgelang ，而不是使用标准的页面规则 UI？

这是最核心的决策问题。您应该在遇到标准 UI 规则无法满足的、复杂的、动态的或对性能有极致要求的场景时，考虑使用 Edgelang。

• 标准规则 UI: 适用于常见的、静态的逻辑，例如“当 URI 是 /path 时，跳转到 new-url”。它简单、直观、开箱即用。
• Edgelang: 适用于需要“编程”逻辑的场景，例如：
  • 条件复杂：需要基于多个请求头、Cookie 、客户端 IP 地理位置等信息进行组合判断。
  • 响应处理：需要动态修改响应体内容（比如在 HTML 中插入 JS 脚本）或响应头。
  • 动态路由：需要根据请求的特定参数（如用户 ID、区域码）来动态选择上游服务。
  • 性能优化：当您有上百条规则时，Edgelang 编译器会将它们优化成高效的单个代码块，其性能通常优于上百条独立页面规则的顺序执行。

🔗 Edgelang 最强大的应用场景是什么？能给个例子吗？

Edgelang 最强大的地方在于其 对请求和响应的深度编程和控制能力。最典型的“杀手级”应用场景是 A/B 测试 和 灰度发布。

示例：基于用户 ID 实现灰度发布 假设您想让用户 ID 尾号为“7”的用户访问新版上游服务 new-backend-upstream，其他用户访问旧版。

# 规则：灰度发布
# 当请求的 cookie 中包含 userid，且 userid 以 '7' 结尾时
req-cookie("userid"), req-cookie("userid") suffix "7" =>
  set-upstream-name("new-backend-upstream");

这个逻辑用标准 UI 规则也可以实现，但用 Edgelang 就更加简洁和高效。

🔗 我写好了一段 Edgelang 代码，如何部署和执行它？

Edgelang 代码并不是独立部署的，而是作为页面规则的一个动作来执行。流程如下：

1. 编写代码：在代码编辑器中编写您的 Edgelang 规则。
2. 创建页面规则：在 Edge Admin 的某个应用下，创建一个新的页面规则。
3. 设置条件：（可选）为您希望执行 Edgelang 的请求设置触发条件，例如 URI路径前缀是 /api/。
4. 选择动作：在规则的“动作”部分，选择“执行 Edgelang”这个动作。
5. 粘贴代码：将您写好的 Edgelang 代码粘贴到动作的输入框中。
6. 保存并发布：保存并发布这条页面规则。

之后，当有请求匹配您设置的条件时，您嵌入的 Edgelang 代码就会被执行。

🔗 Edgelang 的执行顺序是怎样的？它和 WAF、缓存等其他规则如何协作？

Edgelang 作为页面规则的一部分，其执行遵循 Nginx 的处理阶段（Phases）和页面规则的优先级。一个简化的请求处理流程如下：

1. 页面规则（包括 Edgelang 或 WAF）：请求将进入页面规则的处理逻辑。此时，包含 Edgelang 或 WAF 的规则会根据其优先级 （在 UI 上可以拖动排序）和触发条件被执行。
2. 缓存：Edgelang 可以控制后续的行为。例如，您可以在 Edgelang 规则中调用 enable-proxy-cache() 动作来决定是否对某个请求启用缓存。

🔗 Edgelang 的性能和安全性如何？如果我写了有问题的代码怎么办？

• 性能：极高。Edgelang 编译器会将您的规则（甚至是跨多条规则）进行深度分析和优化，生成非常高效的 Lua 代码。其性能通常优于大量独立页面规则的组合。
• 安全性:
  • 编译时检查：Edgelang 编译器会在您保存规则时进行严格的语法和逻辑检查，大部分低级错误（如语法错误、函数名写错）会在此时被发现并阻止保存。
  • 沙箱环境：Edgelang 的执行被限制在一个安全的沙箱环境中，它只能调用手册中列出的内置函数和动作，无法执行任意系统命令或危险操作。
  • 测试：虽然目前没有独立的“空跑”模式，但最佳实践是在一个非生产的应用或服务上先行部署和测试您的 Edgelang 规则，验证其逻辑正确性后，再应用到生产环境。