ghcr.io/openfaas/of-watchdog:0.12.1

of-watchdog

基于 STDIO/HTTP 的函数反向代理/中间件

of-watchdog 会实现在 8080 端口上监听的 HTTP 服务器，作为运行函数和微服务的反向代理使用。它既可独立运行，也可作为 OpenFaaS 容器的入口点。

本版本的 OpenFaaS watchdog 在原有能力外新增了 HTTP 代理与 STDIO 支持，可实现内存复用并提供极快的请求响应速度。它并非用于替代 https://github.com/openfaas/classic-watchdog，而是为有相关需求的用户提供另一种选择。

你可通过 GitHub Releases 获取对应二进制文件，但推荐在多阶段构建中直接从发布到 https://github.com/openfaas/of-watchdog/pkgs/container/of-watchdog 的容器镜像中复制 watchdog，使用方式如下：

FROM --platform=${TARGETPLATFORM:-linux/amd64} ghcr.io/openfaas/of-watchdog:0.9.11 as watchdog
FROM --platform=${TARGETPLATFORM:-linux/amd64} node:18-alpine as ship

COPY --from=watchdog /fwatchdog /usr/bin/fwatchdog

https://github.com/openfaas/templates/

设计目标

• 通过 HTTP 机制保持函数进程常驻，以降低延迟、支持缓存与长连接
• 支持从函数流式输出超大响应，突破容器 RAM 或磁盘容量限制
• 为每种运行模式提供更清晰的抽象定义

运行模式

of-watchdog 提供多种运行模式，不同模式下它与微服务或函数代码的交互逻辑存在差异。

三种 watchdog 模式的对比示意：左上为 Classic Watchdog，右上为已废弃的 afterburn 模式，左下为 of-watchdog 的 HTTP 模式。

1. HTTP 模式 - 为默认选项，也是效率最高的方案；如果目标语言支持 HTTP 服务器实现，所有模板开发者都应优先考虑使用该模式。
2. 序列化模式 - 适用于不支持 HTTP 服务器实现的场景，会将全部 STDIO 内容读入内存后再传入 fork 出的进程。
3. 流式模式 - 与序列化模式逻辑大体相同，但请求和响应都会采用流式传输，不会在函数运行前将所有内容缓冲到内存中。

API 接口

以下为 watchdog 提供的私有接口：

• /_/health - 当进程已启动时返回 true；若配置了锁文件，则锁文件存在时返回 true。
• /_/ready - 逻辑与 /_/health 基本一致，但如果 max_inflight 已配置为非零值，且当前已达最大连接数时，将返回 429 状态码。

其余所有 HTTP 请求处理规则：

• 所有其他路径和 HTTP 方法的请求都将直接转发至函数。

1. HTTP (mode=http)

1.1 状态说明

所有目标语言支持 HTTP 服务器实现的模板，都推荐使用 HTTP 模式。

你可以找到多种不同类型的模板示例，通过 faas-cli template store list 命令可查看完整列表，常见的有 golang-middleware、python3-http 和 node* 等。

如需获取指定模板的代码仓库地址，可执行 faas-cli template store describe NAME 命令。

1.2 功能说明

watchdog 启动时会 fork 出一个常驻进程，之后将所有收到的请求转发至容器内的 HTTP 端口。

优势：

• 高并发、高吞吐量场景下性能最优
• 相比 fork 模型，并发处理效率和内存占用表现更好
• 数据库连接可以在容器的整个生命周期内保持持久化
• 可将初始化任务（如下载文件或模型）一次性执行并存储到 /tmp/ 路径下，后续所有请求都可直接复用
• 不需要像 afterburn 那样引入额外的自定义客户端库，可直接依托 Node 生态的 Express.js 或 Python 生态的 Flask 这类长驻守护进程运行

测试用例：

• 转发请求到 Nginx 容器：

$ go build && mode=http port=8081 fprocess="docker run -p 80:80 --name nginx -t nginx" upstream_url=http://127.0.0.1:80 ./of-watchdog

• 转发请求到 Node.js / Express.js 示例 Hello World 应用：

$ go build && mode=http port=8081 fprocess="node expressjs-hello-world.js" upstream_url=http://127.0.0.1:3000 ./of-watchdog

劣势：

• 在客户端与函数的请求链路中多了一层 HTTP 跳转
• Express、Flask、Sinatra 这类 Web 框架在该部署方式下可能出现不可预期的行为，通常需要额外调整配置
• 与 fork 模型相比，两次请求的间隔时段可能占用更多额外内存

1.3 结构化日志

目前 watchdog 自身的运行日志暂不支持直接以 JSON 格式输出，示例日志如下：

2024/04/25 17:29:06 Listening on port: 8080
2024/04/25 17:29:06 Writing lock-file to: /tmp/.lock
2024/04/25 17:29:06 Metrics listening on port: 8081
2024/04/25 17:29:08 GET / - 301 Moved Permanently - ContentLength: 39B (0.0049s) [test]

但你可以自行输出 JSON 格式的日志行，只需将环境变量 prefix_logs 设置为 false，即可移除 watchdog 默认添加的日志前缀内容。

开启 prefix_logs 时的日志输出效果：

2024-04-24T21:00:04Z {"msg": "unable to connect to database"}

关闭 prefix_logs 时的日志输出效果：

{"msg": "unable to connect to database"}

1.4 链路追踪 / 关联 ID

API 网关会携带 X-Call-Id 头部，你可以在自定义日志中使用该头部的值实现请求关联与链路追踪。

在 HTTP 模式下，若将环境变量 log_callid 设置为 true，watchdog 会将 X-Call-Id 以方括号形式追加到自身的 HTTP 访问日志中，效果如下：

2024/04/25 17:29:58 GET / - 301 Moved Permanently - ContentLength: 39B (0.0037s) [079d9ff9-d7b7-4e37-b195-5ad520e6f797]

1.5 自定义超时时间

如果通过 exec_timeout 为函数设置了较大的超时值（例如 1h），但需要让单个请求的超时时间更短（例如 1m），你可以携带值为 Go 时长格式的 X-Timeout HTTP 头部来覆盖原有超时配置。

X-Timeout 的取值必须小于或等于环境变量 exec_timeout 的值。

当 exec_timeout 设置为 0 或未显式配置时，无法使用 X-Timeout 自定义超时。

2. 序列化 Fork (mode=serializing)

2.1 状态说明

该模式用于复刻初代 watchdog 的行为，提供向后兼容性。

2.2 功能说明

每个请求都会 fork 出新进程，支持多线程，非常适合对已有 CGI 类型应用处理器（例如基于 Flask 的应用）进行快速改造接入。

该模式的处理文件大小受限于可用内存容量。

它会将 HTTP 请求的全部内容读入内存，按需完成序列化或处理后写入标准输入管道：

• 标准输出管道的内容会先被读入内存，按需完成序列化或处理后，再写入到 HTTP 响应中。
• 支持提前设置固定的 Content-type。
• 暂不支持函数执行完成后再设置 HTTP 头部。
• 支持配置执行超时。

3. 流式 Fork (mode=streaming) - 默认模式

每个请求都会 fork 出新进程，可处理超出内存容量的请求体：例如拥有 512MB 内存的虚拟机就可以处理数 GB 大小的视频内容。

由于需要实现流传输效率，函数启动执行后将无法再发送 HTTP 头部，这是因为输入/输出直接与响应挂钩。除非进程派生出现问题，否则响应码始终为 200，过程中出现的错误需要由客户端捕获。该模式支持多线程。

• 执行进程向 stdout 打印内容的同时，输入会立即返回给客户端。
• 可提前设置静态 Content-type。
• 支持 Exec 超时。

4. Static (mode=static)

该模式会启动一个 HTTP 文件服务器，用于托管 static_path 所指定目录下的静态内容。

相关示例可参考 Hugo 博客文章。

指标

配置

环境变量说明：

[!NOTE] 超时时间需要以 Golang 时长格式指定，例如 1m 或 20s。

以下为 https://github.com/openfaas/classic-watchdog 不支持的选项：

OAuth 与 OpenID Connect

watchdog 可以为函数添加基于 OAuth 2.0 或 OpenID Connect (OIDC) 提供商的浏览器登录能力。它会代函数执行带 PKCE 的授权码流程，将生成的会话保存在签名 Cookie 中，并在转发每个请求之前校验该 Cookie，您的函数本身无需自行实现任何认证逻辑。

登录完成后，提供商的访问令牌与 ID 令牌将被丢弃，绝不会存储在 Cookie 中。当提供商返回 ID 令牌时，会话仅保留联合身份声明，与 OpenFaaS IAM 的约定一致：sub 前缀为 fed:，提供商的签发者标识为 fed:iss，存在 email 和 name 字段时也会一并保留。若使用纯 OAuth 模式，会话仅记录该用户已完成登录的状态。

每次请求到达时，of-watchdog 都会校验会话 Cookie 的有效性：

• 无 Cookie：请求将重定向至 {oauth_base_url}/auth/login 登录页面。
• Cookie 有效：请求将被转发至目标函数。
• Cookie 无效或已过期：请求将重定向至登录页面。

of-watchdog 会在函数的公共 URL 下对外提供以下路由：

• GET /auth/login：返回登录页面
• POST /auth/login：启动登录流程，将浏览器重定向至身份提供商的授权 URL
• GET /auth/callback：处理提供商的回调跳转，并设置会话 Cookie
• POST /auth/logout：清除会话 Cookie，并重定向至登录页面

请在你使用的身份提供商及客户端配置中，将 {oauth_base_url}/auth/callback 注册为回调（重定向）URI。

会话 Cookie 采用 HttpOnly 属性并经过签名校验。登出操作仅会清除函数相关 Cookie 并将访客带回登录页面，不会终止访客在身份提供商侧的会话。

必要配置项

设置 oauth_enabled=true，同时提供函数的公共 URL、在身份提供商处注册的客户端 ID 以及一个签名密钥。签名密钥、客户端密钥等敏感信息需从挂载在 /var/openfaas/secrets 路径下的文件中读取。

接下来你可以通过以下两种方式之一，将 of-watchdog 指向你的身份提供商：

• OIDC（推荐）：将 oauth_issuer_url 设置为提供商的签发者 URL。of-watchdog 会自动发现授权端点、令牌端点和密钥端点，自动完成 ID 令牌校验。该模式适用于 Keycloak、Okta、Google、Microsoft Entra ID 及其他支持 OIDC 规范的身份提供商。
• 纯 OAuth：将 oauth_authorization_endpoint 和 oauth_token_endpoint 分别设置为提供商的授权地址和令牌交换地址。该模式适用于不支持 OIDC 自动发现的提供商，例如 GitHub OAuth App。

可选配置项

会话有效期需使用符合 Golang 规范的正时长格式，且精度为整秒，例如 30m 或 8h。