函数
函数(Functions)是 Agentbase 提供的事件驱动、多语言 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 编译等待。多种执行环境:支持本地 OpenRuntimes 与多实例多副本云沙箱(ACS Sandbox)。ACS E2B 和 OpenSandbox 的受限执行路径会检查运行身份与权限;其他执行器的身份和隔离能力应按实际部署核实。调用时通过请求头传递凭据,不要将 API Key 放入 URL 查询参数。
去重执行路径回查与正则/方法过滤(2.9.0 / 2.10.0 增强):支持按函数实际接收到的 HTTP 请求路径(
path)去重聚合,并结合精确匹配/正则匹配(pathMatch=exact|regex)与 HTTP 方法(method)快速检索特定业务接口的历史执行耗时与日志。排查执行失败:可结合执行记录、响应状态、日志与运行环境定位业务或平台问题。不能仅凭 5xx 状态码确定故障来源;执行与构建日志可能被截断。
| 核心能力维度 | 控制台页签位置 | 关键技术规格(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)、函数级变量(与项目全局变量自动合并注入) | 编排事件驱动自动化工作流、绑定函数专属自定义域名 |
核心概念与架构
1. 四大核心对象模型定义
| 核心对象 | 生命周期与唯一标识 | 关键属性与架构说明 |
|---|---|---|
| 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 针对企业广泛使用的 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 应按操作授予权限:查询两个执行路径接口需
execution.read,函数读取或修改分别使用相应的functions.read或functions.write。带启用的 AppBase 标记且 SDK 名为 Web、平台为 client 的请求会被执行记录读取守卫拦截;通过该守卫后仍需满足其他认证和授权要求。客户端终端用户直接调用函数(
POST /v1/functions/{functionId}/executions)则受该函数 Settings → Execute access 中配置的角色选择器(如any、users、team:support_team)控制。
2. 函数级变量与项目全局变量的注入优先级
函数执行时,平台会自动将环境变量注入容器进程中,变量来源包含两层:
项目级全局变量(Global variables):在项目 设置 → 概览 → 全局变量 中维护,对项目下所有 Functions 和 Sites 生效。
函数级专属变量(Function variables):在具体函数的 Settings → Variables 中维护,仅对当前函数生效。
同名冲突提示:当函数级变量与项目全局变量出现相同键名(
Key)时,Console 会在函数变量列表页内显式标出冲突提示,便于开发者核对实际生效值。
功能详解与操作指南
1. 创建云函数(三种来源与算力规格配置)
在函数列表页点击创建函数进入创建页面(/functions/create-function),向导提供且仅提供以下三种创建方式:
方式一:手动上传代码包(支持 .tar.gz 源码或 Java 17 .jar)
在创建页面选择手动上传代码包。
按步骤填写核心表单参数:
| 配置项字段 | 必填/选填 | 参数约束与生产配置建议 |
|---|---|---|
| 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):• 选 source:上传 .tar.gz 源码包,填写 entrypoint 与 install command;• 选 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}),默认展示 部署 页签:
发布新版本:点击右上角 Create deployment,根据需要选择 Manual(手动上传
.tar.gz或.jar)、Git(拉取指定分支/提交) 或 CLI。跟踪构建状态与日志:
构建进行中可随时点击 取消 取消构建。
若构建状态变为
failed,点开 Deployment 查看已记录的构建输出(例如依赖拉取或包格式错误);日志可能截断。修复问题后可对历史部署点击 重新部署 重新构建。
激活上线与一键回滚(Activate):
构建成功(状态
ready)后,若未勾选自动激活,点击该部署右侧的 激活 按钮即可将其切换为当前线上生效版本。生产回滚:当新版本上线后发现业务异常,只需在 Deployments 列表中找到上一个状态为
ready的历史部署,点击 激活,切换激活部署,无需重新编译;随后检查新请求的执行结果,不承诺切换耗时或在途请求无损。
3. 在线触发执行(Execute)与去重执行路径查询(Execution Paths)
切换到函数详情页的 执行 页签(路径 /functions/function-{function}/executions):
A. 在线手动调试或排期执行
点击右上角 执行 按钮打开执行向导弹窗。
填写模拟请求参数:
Path:请求子路径(如
/tickets/validate)。Method:从
GET、POST、PUT、PATCH、DELETE、OPTIONS、HEAD中选择。Headers 与 Body:添加自定义请求头与 JSON 请求体载荷。
执行时机:选择 Run now(立即异步执行) 或 Scheduled at(指定未来具体日期时间单次执行)。
重要安全提示:Execute 会真实运行容器代码并可能读写当前项目的数据库或存储桶,在生产项目中点击提交前请务必确认目标环境与请求参数。
B. 按去重执行路径(Execution Paths)检索与排障(2.10.0 增强)
当单个函数通过内部路由承载了数十个业务子接口时,使用 执行路径查询 可快速定位特定接口的执行情况:
在 执行 页面切换或展开路径查询视图(对应服务端端点
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. 排查执行失败
查看执行记录、状态码、错误、日志和运行环境,再判断原因。业务代码和平台执行链路都可能产生 5xx;日志及错误输出超限时会截断,不能仅凭状态码或缺失日志作结论。
| 响应状态码 | 排查线索 |
|---|---|
| 500 / 502 / 503 / 504 | 可能由业务响应或执行链路产生。结合执行详情、可用日志、超时与平台状态定位;若结果未知,先核对副作用再决定是否重试。 |
D. 补充沙箱诊断与日志缺口
若部署方已启用新版沙箱诊断,平台会隔离保存运行、构建和执行线索,业务代码不能直接读写诊断文件。函数用户可以输出业务日志,但正文和其中自报的项目、执行或 Trace 标识只作关联线索,不能作为访问其他资源的授权依据。
诊断使用固定轮转与有界队列;采集器启动较晚时会在后台重试,队列满、存储故障、实例强杀或退出超时仍可能丢日志。可用磁盘低于保留余量时会停止新增诊断写入,空间恢复后可继续;这不等于函数获得磁盘硬配额。若执行存在而日志缺失,请保留执行 ID、发生时间和平台状态,交由管理员结合生命周期和采集健康记录排查,不能据此认定业务没有执行。
执行关闭日志(logging=false)时,不新增该请求的业务 logger 正文,同实例后续 runtime raw 采集也会保持关闭;尚未被采集器接收的队列正文会被拒绝,已进入写入队列的内容仍可能完成落盘。旧执行日志回传规则保持原有语义;后续开启日志的明确 logger 事件按运行时语义记录。函数返回成功、文件写完或本地结束摘要都不证明诊断已上传。平台升级需配套更新运行时与采集组件,tag 存在不能证明当前环境已部署这些行为。
4. 配置定时任务(Schedule)、事件触发、监控与自定义域名
定时执行(Cron Schedule):进入函数 设置 页签,在 Schedule 卡片中输入标准 Cron 表达式(界面自带实时 Cron 语法校验,例如
0 */2 * * *表示每 2 小时整点执行一次),点击保存后即由平台调度器自动周期触发。事件触发(Events):在 Settings → Events 中添加内部事件订阅(如
databases.enterprise_biz_db.tables.customer_tickets.rows.create),当业务库新增工单行时自动将行数据作为请求体触发函数。ACS 容器组算力监控(Usage):切换到 用量 页签,除了查看执行次数与平均耗时趋势外,针对运行在云沙箱(ACS)上的函数,页面下方专门提供 ACS 容器组资源监控面板,实时展示容器实例的 CPU 利用率、内存占用、网络吞吐与磁盘读写,为调优
runtimeSpecification与runtimeReplicas提供量化依据。函数专属域名(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 服务使用。
打开函数 → 创建函数 → 手动上传代码包,运行时选择 Java 17;已有 Java 17 函数可从部署列表进入手动上传。
确认上传模式为预构建 JAR,选择
.jar文件。需要在线构建源码时切回源码模式,上传.tar.gz;不要只把文件扩展名改成 JAR。确认执行规格、副本数、变量和执行权限。JAR 模式不需要填写源码入口、安装命令或构建规格;应用入口取自 manifest。部署记录中的
Index.java是兼容标识,无需为此额外创建同名源码文件。提交后等待部署记录出现,记录部署 ID,检查构建状态和日志。默认 JAR 大小限制为 100 MB(100,000,000 字节),还受套餐部署上限约束;超限时缩小产物或联系管理员确认有效上限。
部署达到 ready 后,确认它已成为当前激活部署;按需使用 激活。再通过 执行 发起一次实际请求,检查返回状态码、响应体与日志。
| 检查点 | 可以确认什么 | 下一步 |
|---|---|---|
| 上传进度达到 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 权限跑起来?
原因与排查步骤: ACS E2B 与 OpenSandbox 的受限执行路径会在启动准备时检查非 root 身份、权限能力和 NoNewPrivs;安全检查失败会拒绝该路径的执行。权限不足时,具体命令的报错和退出行为由运行环境及脚本决定。请检查所用执行器、镜像和运行日志,将临时文件放在可写的工作目录或 /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 字节)及套餐部署上限共同约束;超出有效上限时精简依赖或联系管理员确认套餐和部署配置。
相关文档
多条定时任务与 CPU 优先规格
同一个函数可以有多条独立的定时任务。每条任务维护自己的规则、参数和启停状态,执行时使用当前 ready 的活动部署。进入 函数 → 目标函数 → Settings → 调度,先检查活动部署,再点击新建。选择规则类型,填写规则、时区或固定周期起点,设置参数类型并明确是否启用,保存后重新打开详情核对。
| 设置 | 含义与边界 |
|---|---|
| 固定周期 interval | 1–2147483647 秒;起点为精确到秒的 UTC 时间,创建时留空使用创建时刻 |
| Cron | 五字段表达式;未提供时区使用 UTC |
| Quartz | 六字段,可附年份;日和星期恰好一个为 ?,支持 IANA 时区 |
| JSON 参数 | 通过 POST / 调用;输入合法 JSON,空输入表示不传参数 |
| 请求路径 | 通过 GET 调用当前函数的相对路径与 query,例如 /daily-report?region=east;不是外部 URL,无请求体 |
| 启停 | 各任务独立;停用期间的触发点不会补跑,停用不撤销已准入执行 |
固定周期编辑时起点留空保留原锚点,填写新时间才修改。创建后不能改变任务类型;需要另一类型时新建任务,再停用旧任务。请求路径以单个 / 开头,含 query 最多 2048 字节,不能包含完整 URL、fragment、空白或无效百分号编码。
列表支持分页、新建、编辑、启停和确认删除。保存后查看规则、启用状态与下次触发时间,再进入执行记录核对实际结果;下次时间或创建成功不表示业务已执行。函数的 enabled 开关限制客户端主动调用,不替代任务的启停开关。运行时保活独立管理,删除业务任务不会关闭保活。
旧单 Cron 设置只反映标为 compact 的历史任务,不能据此判断全部任务;历史任务也可编辑或删除,删除后旧入口不会自动复活。没有执行时,依次检查任务启用、规则时区、活动部署 ready 状态及项目可写性。保存失败保留表单输入,先修正提示再提交,避免重复创建。
执行规格新增 1 CPU / 1024 MB 和 2 CPU / 2048 MB。在函数设置中选择并保存后重新打开核对;可用值仍受套餐与部署资源约束。规格变更沿用运行时回收规则,建议在没有执行任务时调整。
