函数
函数(Functions)是 Agentbase 2.10.0 提供的事件驱动、多语言 Serverless 服务端代码执行引擎。它支持通过 HTTP 请求直接调用、按内部业务事件(如数据库新增工单、用户注册、文件上传)自动触发或按 Cron 表达式定时执行,并提供从源码构建(.tar.gz / Git)到 **Java 17 预构建 JAR 包直接部署(artifactMode=java-jar)、去重执行路径查询(Execution Paths)以及云沙箱(ACS Sandbox)容器组资源监控**的完整生产级能力。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
功能概述
在构建企业级 AI 与智能体应用(如项目 企业智能客服与知识中台 enterprise-ai-hub-210)时,许多自定义业务逻辑需要运行在安全受控的服务端沙箱中:例如当客户在 customer_tickets 表提交紧急工单(TK-20261022-001)时,自动触发函数调用企业内部 ERP 接口核验合同等级;或者将复杂的 Java 17 企微/钉钉加解密逻辑打包为独立工具函数供智能体调用。
Agentbase Functions 围绕企业高并发与高安全标准提供四大核心特性:
- 多语言运行时与 Java 17 预构建 JAR 直传(2.10.0 增强):支持 Node.js、Python、PHP、Ruby、Deno 以及 **
java-17.0等多种运行时;针对 Java 17 企业工程,除传统的源码压缩包构建外,新增artifactMode=java-jar预构建 JAR 直接部署模式**(JAR 配置默认上限 100 MB,实际还受套餐部署上限约束),免除云端漫长的 Maven/Gradle 编译等待。 - 受限身份云沙箱(ACS Sandbox)与零回退安全执行:支持本地 OpenRuntimes 与多实例多副本云沙箱(ACS Sandbox)执行面;所有函数强制以非特权受限身份(Restricted Identity)运行,并内置出站 SSRF 防护与请求头凭据保护(禁止通过 URL Query String 传递 API Key)。
- 去重执行路径回查与正则/方法过滤(2.9.0 / 2.10.0 增强):支持按函数实际接收到的 HTTP 请求路径(
path)去重聚合,并结合精确匹配/正则匹配(pathMatch=exact|regex)与 HTTP 方法(method)快速检索特定业务接口的历史执行耗时与日志。 - 平台故障与业务异常精准解耦:在执行列表与详情日志中,清晰区分沙箱基础设施异常(
502/503/504)与业务代码自身异常(500,完整保留业务崩溃日志),并提供 ACS 容器组 CPU、内存、网络与磁盘水位监控。
| 核心能力维度 | 控制台页签位置 | 关键技术规格(2.10.0 基线) | 适用研发与运维场景 |
|---|---|---|---|
| 创建与部署(Deployments) | 函数详情 Deployments | 三种来源:Git 仓库、模板库、手动上传(.tar.gz 源码或 java-17.0 预构建 .jar) | 持续集成发布、一键切换激活版本(Activate)与回滚历史版本 |
| 执行与路径回查(Executions) | 函数详情 Executions | 支持立即/定时手动触发;支持去重执行路径分页与 path/pathMatch/method 过滤 | 在线接口联调、按具体 REST 子路径(如 /webhook/erp-sync)精准排查慢请求与报错 |
| 算力规格与监控(Usage) | 函数详情 Usage · Settings | 支持配置 CPU/内存规格(runtimeSpecification)与副本数(runtimeReplicas);支持平台默认规格 | 观察执行次数、平均耗时及 ACS 云沙箱容器组的 CPU/内存/网络/磁盘实时曲线 |
| 触发器与变量(Settings) | 函数详情 Settings · Domains | 事件触发(Events)、定时任务(Cron Schedule)、函数级变量(与项目全局变量自动合并注入) | 编排事件驱动自动化工作流、绑定函数专属自定义域名 |
核心概念与架构
下图展示了 Functions 从代码/JAR 包部署、三种触发方式(HTTP / 事件 / Cron)、项目上下文与变量注入,到在受限身份 ACS 云沙箱中执行并产出路径索引与监控指标的全链路架构:
flowchart TB
subgraph DeploySources["部署来源与产物模式 (Deployment)"]
GitSrc["1. Git 仓库连接<br/>GitHub 分支/Commit 自动构建"]
TplSrc["2. 官方模板库 (Templates)<br/>Starter 快速开始 / 精选模板"]
ManualSrc["3. Manual 手动上传<br/>a) artifactMode=source (.tar.gz 源码包)<br/>b) artifactMode=java-jar (Java 17 预构建 JAR, 受有效大小上限约束)"]
end
subgraph TriggerPlane["三大触发入口 (Triggers)"]
HTTPTrig["HTTP / SDK / 自定义域名调用<br/>(严禁 Query String 传 Key, 强制 Header 鉴权)"]
EventTrig["平台内部事件触发 (Events)<br/>例如 databases.*.tables.*.rows.create"]
CronTrig["Cron 定时调度 (Schedule)<br/>标准 Cron 表达式周期触发"]
end
subgraph SandboxRuntime["执行面:OpenRuntimes / ACS 云沙箱 (Restricted Identity)"]
ContextInject["自动注入项目上下文:<br/>项目 Global variables + 函数级 Variables (同名覆盖提示)<br/>+ runtimeSpecification (CPU/内存) + runtimeReplicas (多副本)"]
ExecEngine["受限身份容器执行 (Node / Python / java-17.0 等)<br/>出站 SSRF 防护 + 平台错误 (502/503/504) 与业务错误 (500) 隔离"]
ContextInject --> ExecEngine
end
subgraph ObsAndQuery["执行记录与容器监控"]
PathIndex["去重执行路径查询 (Execution Paths)<br/>path + pathMatch (exact/regex) + method 过滤"]
ACSMonitor["Usage 与 ACS 容器组监控<br/>执行次数 / 耗时 + CPU / 内存 / 网络 / 磁盘水位"]
end
GitSrc --> SandboxRuntime
TplSrc --> SandboxRuntime
ManualSrc --> SandboxRuntime
HTTPTrig --> SandboxRuntime
EventTrig --> SandboxRuntime
CronTrig --> SandboxRuntime
ExecEngine --> PathIndex
ExecEngine --> ACSMonitor1. 四大核心对象模型定义
| 核心对象 | 生命周期与唯一标识 | 关键属性与架构说明 |
|---|---|---|
| Function(函数定义) | 归属 Project,拥有唯一 $id | 定义运行时语言(runtime,创建后固定)、算力规格(runtimeSpecification)、实例副本数(runtimeReplicas)、执行权限(execute ACL)、超时时间(timeout)、触发事件与 Cron 计划。 |
| Deployment(部署版本) | 归属 Function,每次上传/提交生成新 $id | 承载一次具体的代码或预构建 JAR 产物。经历 waiting → building → ready / failed 构建流转;同一时刻仅有一个 ready 部署处于 Active(当前激活) 状态对外提供服务。 |
| Execution(单次执行) | 归属 Function,每次触发生成唯一记录 | 记录单次调用的请求方法(method)、请求路径(path)、耗时(duration)、HTTP 响应状态码(responseStatusCode)、标准输出(logs)与错误输出(errors)。 |
| Execution Path(去重执行路径) | 服务端自动按请求 path 聚合 | 将海量 Execution 记录按实际访问的子路径(如 /v1/sync、/v1/callback)去重归类,支持服务端分页与正则/方法过滤。 |
2. 源码构建模式(source)与 Java 17 预构建 JAR 模式(java-jar)对比
在 Agentbase 2.10.0 中,针对企业广泛使用的 java-17.0 运行时,提供了两种截然不同的部署产物模式(artifactMode):
| 对比维度 | 源码包构建模式(artifactMode = source) | Java 17 预构建 JAR 模式(artifactMode = java-jar,2.10.0 新增) |
|---|---|---|
| 适用运行时 | 全部受支持运行时(Node.js、Python、PHP、Ruby、Deno、Go、java-17.0 等) | **仅限 java-17.0 运行时** |
| 上传产物格式 | .tar.gz 源码压缩包 | 在本地或企业 CI 流水线预先编译打包好的 **.jar 文件** |
| 构建与入口机制 | 容器内执行 install command 拉取依赖并编译源码,按自定义 entrypoint 启动 | 免除云端源码编译,直接使用预构建 JAR 作为部署产物,使用 manifest 的 Main-Class;Index.java 仅为部署记录兼容标识 |
| 包体积限制与计量 | 受通用计算源码包上限(_APP_COMPUTE_SIZE_LIMIT / 套餐 deploymentSize)约束 | 由 _APP_FUNCTIONS_JAR_SIZE_LIMIT(默认 100,000,000 字节)与套餐 deploymentSize 共同限制,以有效上限为准 |
角色、入口与关联关系
1. 控制台导航路径与权限要求
- 进入函数模块:在项目控制台左侧导航栏点击 Functions(函数),进入
/console/project-{region}-{project}/functions(如图 1 所示)。 - 权限与 Scope 映射:
- 在 Console 创建、修改配置或上传部署包需要项目写角色(
owner/admin/developer/editor,对应functions.write)。 - 通过服务端 API Key 管理函数或查询去重执行路径(
GET /v1/functions/{functionId}/execution-paths)需要functions.read/functions.write/execution.readScope(注意:执行路径查询接口专为服务端治理设计,客户端 Web SDK 调用受限)。 - 客户端终端用户直接调用函数(
POST /v1/functions/{functionId}/executions)则受该函数 Settings → Execute access 中配置的角色选择器(如any、users、team:support_team)控制。
- 在 Console 创建、修改配置或上传部署包需要项目写角色(
2. 函数级变量与项目全局变量的注入优先级
函数执行时,平台会自动将环境变量注入容器进程中,变量来源包含两层:
- 项目级全局变量(Global variables):在项目 Settings → Overview → Global variables 中维护,对项目下所有 Functions 和 Sites 生效。
- 函数级专属变量(Function variables):在具体函数的 Settings → Variables 中维护,仅对当前函数生效。
- 同名冲突提示:当函数级变量与项目全局变量出现相同键名(
Key)时,Console 会在函数变量列表页内显式标出冲突提示,便于开发者核对实际生效值。
功能详解与操作指南
1. 创建云函数(三种来源与算力规格配置)
点击 Functions 列表页右上角的 Create function 进入创建向导(/functions/create-function),向导提供且仅提供以下三种创建方式:
方式一:通过手动配置创建(Manual,支持 .tar.gz 源码或 Java 17 .jar)
- 在创建向导中选择 Manual(手动创建)。
- 按步骤填写核心表单参数:
| 配置项字段 | 必填/选填 | 参数约束与生产配置建议 |
|---|---|---|
| Name(函数名称) | 必填 | 输入清晰的业务名称(如 erp-ticket-escalation-fn),可选自定义 **Function ID($id)**。 |
| Runtime(运行时) | 必选 | 从当前部署实例允许的运行时列表中选择(如 node-18.0、python-3.11、**java-17.0**)。注意:函数创建后运行时类型不可直接切换。 |
| Artifact Mode(产物模式) | 必选(Java 17) | 当 Runtime 选择 java-17.0 时,可选择 **源码包(source) 或 预构建 JAR(java-jar)**:<br/>• 选 source:上传 .tar.gz 源码包,填写 entrypoint 与 install command;<br/>• 选 java-jar:上传满足有效大小上限的 .jar 包,应用入口取自 manifest 的 Main-Class。 |
**CPU / 内存规格(runtimeSpecification)** | 必选 | 选择函数执行容器的算力规格(如 0.5C / 1G、1C / 2G 等)。若平台管理员配置了默认执行规格(defaultRuntimeSpecification),向导会自动预选该规格;若无可用规格请联系管理员发布 execution profile。 |
**副本数(runtimeReplicas)** | 必选 | 设置并发承载的沙箱实例副本数,高并发生产函数建议配置多副本以消除冷启动毛刺。 |
| Execute Access(执行权限) | 选填 | 配置允许直接触发该函数的客户端角色(如 users);若仅由后端 API Key 或内部事件触发,保持为空(默认拒绝客户端直接调用)最安全。 |
方式二:从官方模板创建(Templates)
- 在向导中选择 Starter(快速开始模板,支持切换不同语言运行时) 或点击浏览完整模板库(
/functions/templates),一键生成带标准目录结构与入口代码的初始函数。
方式三:连接 Git 仓库创建(Git Repository)
- 通过已连接的 GitHub VCS 安装选择目标代码仓库、分支与根目录(Root directory),后续每次向该分支推送代码提交(Push)均可自动触发新 Deployment 构建。
2. 管理部署版本(Deployments)与一键回滚
进入具体函数详情页(/functions/function-{function}),默认展示 Deployments 页签:
- 发布新版本:点击右上角 Create deployment,根据需要选择 **Manual(手动上传
.tar.gz或.jar)、Git(拉取指定分支/提交) 或 CLI**。 - 跟踪构建状态与日志:
- 构建进行中可随时点击 Cancel 取消构建。
- 若构建状态变为
failed,点开该 Deployment 查看完整构建输出日志(例如 Maven 依赖拉取失败或包格式错误),修复后可对历史部署点击 Redeploy 重新构建。
- 激活上线与一键回滚(Activate):
- 构建成功(状态
ready)后,若未勾选自动激活,点击该部署右侧的 Activate 按钮即可将其切换为当前线上生效版本。 - 生产回滚:当新版本上线后发现业务异常,只需在 Deployments 列表中找到上一个状态为
ready的历史部署,点击 Activate,切换激活部署,无需重新编译;随后检查新请求的执行结果,不承诺切换耗时或在途请求无损。
- 构建成功(状态
3. 在线触发执行(Execute)与去重执行路径查询(Execution Paths)
切换到函数详情页的 Executions 页签(路径 /functions/function-{function}/executions):
A. 在线手动调试或排期执行
- 点击右上角 Execute 按钮打开执行向导弹窗。
- 填写模拟请求参数:
- Path:请求子路径(如
/tickets/validate)。 - Method:从
GET、POST、PUT、PATCH、DELETE、OPTIONS、HEAD中选择。 - Headers 与 Body:添加自定义请求头与 JSON 请求体载荷。
- 执行时机:选择 Run now(立即异步执行) 或 Scheduled at(指定未来具体日期时间单次执行)。
- Path:请求子路径(如
- 重要安全提示:Execute 会真实运行容器代码并可能读写当前项目的数据库或存储桶,在生产项目中点击提交前请务必确认目标环境与请求参数。
B. 按去重执行路径(Execution Paths)检索与排障(2.10.0 增强)
当单个函数通过内部路由承载了数十个业务子接口时,使用 执行路径查询 可快速定位特定接口的执行情况:
- 在 Executions 页面切换或展开路径查询视图(对应服务端端点
GET /v1/functions/{functionId}/execution-paths)。 - 系统自动将该函数已产生执行记录的请求路径去重并按字典升序分页展示。
- 使用 2.10.0 高级过滤条件:
- **路径匹配模式(
pathMatch)**:支持exact(完整路径精确匹配,默认)或regex(正则表达式匹配,如^/api/v1/tickets/[0-9]+$)。 - **路径关键字(
path)**:输入目标路径字符串或正则表达式。 - **HTTP 方法过滤(
method)**:精确筛选特定方法(如仅看POST请求)。
- **路径匹配模式(
- 点击目标路径后,即可调用
GET /v1/functions/{functionId}/execution-paths/executions列出该路径下的全部执行明细。
C. 区分平台沙箱故障与业务代码异常
在查看失败的执行记录详情时,请根据响应状态码与日志面板精准定界:
| 响应状态码 | 故障归属分类 | 具体含义与排障方向 |
|---|---|---|
| 500 | 业务代码失败(Business Failure) | 函数容器已正常启动,但你的业务代码抛出了未捕获异常或主动返回了 500。Console 会完整保留该次执行的业务日志(Logs / Errors),请直接根据堆栈信息修复代码。 |
| 503 | 平台失败:沙箱创建异常 | 底层计算集群算力不足或沙箱创建失败。请检查 ACS 资源池水位或联系平台管理员。 |
| 504 | 平台失败:启动或执行超时 | 容器冷启动超时,或业务代码执行耗时超过了函数 Settings → Timeout 设定的秒数上限(如等待下游慢接口)。请调高函数 Timeout 或优化下游调用。 |
| 502 | 平台失败:执行链路异常 | 网关与运行时沙箱之间的内部通信链路中断,或者是用户启动命令违反了受限身份安全条件被沙箱直接终止。 |
4. 配置定时任务(Schedule)、事件触发、监控与自定义域名
- 定时执行(Cron Schedule):进入函数 Settings 页签,在 Schedule 卡片中输入标准 Cron 表达式(界面自带实时 Cron 语法校验,例如
0 */2 * * *表示每 2 小时整点执行一次),点击保存后即由平台调度器自动周期触发。 - 事件触发(Events):在 Settings → Events 中添加内部事件订阅(如
databases.enterprise_biz_db.tables.customer_tickets.rows.create),当业务库新增工单行时自动将行数据作为请求体触发函数。 - ACS 容器组算力监控(Usage):切换到 Usage 页签,除了查看执行次数与平均耗时趋势外,针对运行在云沙箱(ACS)上的函数,页面下方专门提供 ACS 容器组资源监控面板,实时展示容器实例的 CPU 利用率、内存占用、网络吞吐与磁盘读写,为调优
runtimeSpecification与runtimeReplicas提供量化依据。 - 函数专属域名(Domains):切换到 Domains 页签,可为当前函数独立绑定自定义域名(如
webhook-erp.enterprise.example.com),外部系统可直接向该域名发送请求触发函数。
确认执行规格
创建向导会优先预选当前项目可用的平台默认规格。提交前检查 CPU、内存和副本数是否适合实际负载;手工选择的有效规格优先于默认值。如果没有可用的平台默认规格,按页面列出的可用规格选择,不要直接照抄其他项目的配置。
默认值只影响新建 Function;已有函数不会随平台默认值改变。编辑已有函数时确认保留原执行规格,尤其不要在只调整副本数时顺带改掉规格。执行规格与构建资源是不同配置,调整执行规格不代表构建资源同时改变,也不代表实例已预热。
上传 Java 17 预构建 JAR
适用于已在本地或 CI 构建好的 Java HTTP 服务。准备支持 Java 17 的可执行 JAR:manifest 必须声明 Main-Class,包内必须包含对应入口类;应用监听端口 3000 并提供 /__opr/health 健康检查。仅执行后退出的命令行 JAR 不能作为函数 HTTP 服务使用。
- 打开 Functions → 创建函数 → Manual,运行时选择 Java 17;已有 Java 17 函数可从部署列表进入手动上传。
- 确认上传模式为预构建 JAR,选择
.jar文件。需要在线构建源码时切回源码模式,上传.tar.gz;不要只把文件扩展名改成 JAR。 - 确认执行规格、副本数、变量和执行权限。JAR 模式不需要填写源码入口、安装命令或构建规格;应用入口取自 manifest。部署记录中的
Index.java是兼容标识,无需为此额外创建同名源码文件。 - 提交后等待部署记录出现,记录部署 ID,检查构建状态和日志。默认 JAR 大小限制为 100 MB(100,000,000 字节),还受套餐部署上限约束;超限时缩小产物或联系管理员确认有效上限。
- 部署达到 ready 后,确认它已成为当前激活部署;按需使用 Activate。再通过 Execute 发起一次实际请求,检查返回状态码、响应体与日志。
| 检查点 | 可以确认什么 | 下一步 |
|---|---|---|
| 上传进度达到 100% | 文件传输结束 | 等待创建部署请求返回,不要重复上传 |
| 已返回部署记录 | 服务已接收部署 | 等待状态达到 ready;failed/canceled 时查看日志 |
| 部署 ready | 产物准备完成 | 检查当前激活部署是否为本次部署 |
| 激活部署一致且请求结果符合预期 | 本次代码已实际执行 | 再启用业务流量或定时任务 |
无法提交时先检查运行时、上传模式、JAR 大小及 manifest;部署失败时查看构建日志;部署 ready 但调用失败时检查端口、健康检查、变量、执行权限和执行日志。不要把上传成功当作上线成功。
按 Path 和 Method 排查执行
在函数详情 Executions → 自定义筛选 中填写 Path,选择精确匹配或正则匹配,再按需选择 Method,应用筛选后从第一页查看结果。刷新会保留筛选条件;排查完使用清除操作恢复完整列表。
| 排查目标 | 示例条件 | 注意事项 |
|---|---|---|
| 某个完整请求路径 | Path 精确匹配 /articles/42 | 查询字符串参与匹配,/articles/42?draft=1 是不同路径 |
| 一组编号路径 | Path 正则 ^/articles/[0-9]+$ | 不额外包裹 /…/ 分隔符;此表达式不匹配带查询字符串的路径 |
| 只看读取请求 | Method 选择 GET | 方法与路径条件同时生效,先核对真实请求方法 |
空列表只表示当前条件未命中;先清除筛选核对记录确实存在,再逐项加回条件。waiting / processing 仍表示等待或处理中,不能仅凭已过 timeout 就当作 failed。服务实际记录失败后才会进入失败筛选。运行中的记录不能删除;completed、failed 可删除记录,删除 scheduled 记录会取消对应计划执行。
常见问题与排障
Q1:外部系统通过 URL Query String(如 ?key=standard_xxx)调用受保护的云函数为什么返回 401 鉴权失败?
原因与排查步骤: 出于严密的安全合规要求,Agentbase 禁止通过 URL Query String 传递 Function API Key(因为 URL 参数极易在浏览器历史、反向代理 Access Log 与监控链路中明文泄露凭据)。调用受保护的云函数时,必须将密钥放在受保护的 HTTP 请求头中传递(如 X-Appwrite-Key: standard_...),或使用平台注入的运行时内部认证路径。
Q2:部署或运行函数时报错“不满足受限身份安全条件(Restricted Identity)”,为什么没有自动用 root 权限跑起来?
原因与排查步骤: Agentbase 的 Functions 与 Sites 容器强制执行受限非特权身份运行 + Fail-Closed(失败即拒绝)策略:当你的构建脚本、启动命令或二进制文件尝试执行需要高权限的操作(如修改系统目录、绑定特权端口或切换系统用户)时,沙箱会立即终止并直接报错,**绝不会静默回退为高权限 root 身份执行**。请将临时文件读写路径全部指向工作目录或 /tmp,并移除任何提权指令后重新部署。
Q3:使用 Java 17 预构建 JAR 模式(artifactMode=java-jar)上传部署包时需要注意什么?
原因与排查步骤:
- 检查运行时类型:
artifactMode=java-jar仅在函数 Runtime 为 **java-17.0** 时可用。 - 检查入口类约定:预构建 JAR 模式下,manifest 必须声明
Main-Class,包内包含对应入口类和运行依赖;应用监听3000并提供/__opr/health。Index.java仅为部署记录兼容标识。 - 检查 JAR 文件体积:预构建 JAR 受
_APP_FUNCTIONS_JAR_SIZE_LIMIT(默认 100 MB,即 100,000,000 字节)及套餐部署上限共同约束;超出有效上限时精简依赖或联系管理员确认套餐和部署配置。