diff --git a/.gitignore b/.gitignore index 3de7cfe..4eb4ca3 100644 --- a/.gitignore +++ b/.gitignore @@ -52,6 +52,7 @@ bin/ *.log # VitePress +docs/.vitepress/dist/ docs/.vitepress/cache/ docs/node_modules/ docs/public/swagger.json @@ -63,3 +64,6 @@ openapi_docs/ # Builtin SDK (Force Include) !builtin/ !builtin/** +builtin/**/__pycache__/ +builtin/**/*.pyc + diff --git a/builtin/nodejs/env.js b/builtin/nodejs/env.js new file mode 100644 index 0000000..a1f4b53 --- /dev/null +++ b/builtin/nodejs/env.js @@ -0,0 +1,182 @@ +const http = require('http'); +const https = require('https'); +const { URL } = require('url'); + +/** + * 内部 API 请求辅助函数 + */ +function request(urlStr, method = 'GET', data = null) { + const token = process.env.BHPKG_OPENAPI_TOKEN || process.env.OPENAPI_TOKEN || process.env.BHPKG_NOTIFY_TOKEN; + if (!token) { + throw new Error("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量,无法使用环境管理操作"); + } + + const parsedUrl = new URL(urlStr); + const protocol = parsedUrl.protocol === 'https:' ? https : http; + + let payload = ''; + const headers = { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}` + }; + + if (data !== null) { + payload = JSON.stringify(data); + headers['Content-Length'] = Buffer.byteLength(payload); + } + + const options = { + hostname: parsedUrl.hostname, + port: parsedUrl.port, + path: parsedUrl.pathname + (parsedUrl.search || ''), + method: method, + headers: headers + }; + + return new Promise((resolve, reject) => { + const req = protocol.request(options, (res) => { + let body = ''; + res.setEncoding('utf8'); + res.on('data', (chunk) => body += chunk); + res.on('end', () => { + if (res.statusCode >= 200 && res.statusCode < 300) { + try { + resolve(body ? JSON.parse(body) : {}); + } catch (e) { + resolve(body); + } + } else { + let errMsg = body; + try { + const parsed = JSON.parse(body); + errMsg = parsed.msg || parsed.message || body; + } catch(e) {} + reject(new Error(`请求失败 [${res.statusCode}]: ${errMsg}`)); + } + }); + }); + + req.on('error', (e) => reject(e)); + if (payload) { + req.write(payload); + } + req.end(); + }); +} + +function getEnvsUrl() { + const url = process.env.BHPKG_OPENAPI_URL || process.env.OPENAPI_URL; + if (url) return url; + + const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send'; + const targets = ['/api/v1/notify/send/', '/api/v1/notify/send', '/api/v1/notify/', '/api/v1/notify']; + for (const target of targets) { + if (notifyUrl.includes(target)) { + return notifyUrl.replace(target, '/open2api/v1/env'); + } + } + return 'http://localhost:8052/open2api/v1/env'; +} + +/** + * 获取所有的环境变量列表 + */ +async function getEnvs() { + const url = `${getEnvsUrl()}/all`; + const res = await request(url, 'GET'); + return res.data || []; +} + +/** + * 根据变量名获取环境变量,不存在则返回 null + */ +async function getEnv(name) { + const envs = await getEnvs(); + for (const env of envs) { + if (env.name === name) { + return env; + } + } + return null; +} + +/** + * 批量添加环境变量 + */ +async function addEnvs(envsList) { + const url = getEnvsUrl(); + const addedEnvs = []; + for (const env of envsList) { + if (!env.name || !env.value) { + throw new Error("环境变量必须包含 'name' 和 'value'"); + } + const res = await request(url, 'POST', env); + if (res.data) { + addedEnvs.push(res.data); + } + } + return addedEnvs; +} + +/** + * 添加单个环境变量 + */ +async function addEnv(name, value, remark = "", type = "normal", hidden = true, enabled = true) { + const url = getEnvsUrl(); + const payload = { + name, + value, + remark, + type, + hidden, + enabled + }; + const res = await request(url, 'POST', payload); + return res.data; +} + +/** + * 根据 ID 更新环境变量 + */ +async function updateEnv(id, name, value, remark = null, type = null, hidden = null, enabled = null) { + const url = `${getEnvsUrl()}/${id}`; + const payload = {}; + if (name !== null) payload.name = name; + if (value !== null) payload.value = value; + if (remark !== null) payload.remark = remark; + if (type !== null) payload.type = type; + if (hidden !== null) payload.hidden = hidden; + if (enabled !== null) payload.enabled = enabled; + + const res = await request(url, 'PUT', payload); + return res.data; +} + +/** + * 批量删除环境变量 + */ +async function deleteEnvs(ids) { + for (const id of ids) { + await deleteEnv(id); + } + return true; +} + +/** + * 根据 ID 删除指定环境变量 + */ +async function deleteEnv(id) { + const url = `${getEnvsUrl()}/${id}`; + await request(url, 'DELETE'); + return true; +} + +module.exports = { + getEnvs, + getEnv, + addEnvs, + addEnv, + updateEnv, + deleteEnvs, + deleteEnv +}; diff --git a/builtin/nodejs/index.js b/builtin/nodejs/index.js index 70287cc..7cbb6ec 100644 --- a/builtin/nodejs/index.js +++ b/builtin/nodejs/index.js @@ -1,57 +1,37 @@ -const http = require('http'); -const https = require('https'); -const { URL } = require('url'); +const { notify } = require('./notify'); +const { + getEnvs, + getEnv, + addEnvs, + addEnv, + updateEnv, + deleteEnvs, + deleteEnv +} = require('./env'); +const { + getTasks, + getTask, + updateTask, + deleteTask, + executeTask, + stopTask, + getLastResults +} = require('./task'); -/** - * 环境变量强校验:导入期进行 - */ -const TOKEN = process.env.BHPKG_NOTIFY_TOKEN; -const CHANNEL = process.env.BHPKG_NOTIFY_CHANNEL; - -if (!TOKEN || !CHANNEL) { - const missing = []; - if (!TOKEN) missing.push("BHPKG_NOTIFY_TOKEN"); - if (!CHANNEL) missing.push("BHPKG_NOTIFY_CHANNEL"); - - throw new Error(`缺少必要的环境变量以使用 baihu 模块: ${missing.join(", ")}。请在白虎面板的任务设置中配置这些 Key。`); -} - -/** - * 发送通知的辅助函数 (仅使用 Node.js 标准库) - */ -function notify(title, text, channelId) { - const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send'; - const cid = channelId || CHANNEL; - - if (!notifyUrl || !TOKEN || !cid) return; - - - const parsedUrl = new URL(notifyUrl); - const protocol = parsedUrl.protocol === 'https:' ? https : http; - - const data = JSON.stringify({ - channel_id: cid, - title: title || '系统通知', - text: text - }); - - const options = { - hostname: parsedUrl.hostname, - port: parsedUrl.port, - path: parsedUrl.pathname + (parsedUrl.search || ''), - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'notify-token': TOKEN, - 'Content-Length': Buffer.byteLength(data) - } - }; - - const req = protocol.request(options); - req.on('error', (e) => {}); - req.write(data); - req.end(); - -} - -module.exports = { notify }; +module.exports = { + notify, + getEnvs, + getEnv, + addEnvs, + addEnv, + updateEnv, + deleteEnvs, + deleteEnv, + getTasks, + getTask, + updateTask, + deleteTask, + executeTask, + stopTask, + getLastResults +}; diff --git a/builtin/nodejs/notify.js b/builtin/nodejs/notify.js new file mode 100644 index 0000000..44da672 --- /dev/null +++ b/builtin/nodejs/notify.js @@ -0,0 +1,51 @@ +const http = require('http'); +const https = require('https'); +const { URL } = require('url'); + +/** + * 发送通知的辅助函数 (仅使用 Node.js 标准库) + */ +function notify(title, text, channelId) { + const token = process.env.BHPKG_NOTIFY_TOKEN; + const channel = process.env.BHPKG_NOTIFY_CHANNEL; + + if (!token || !channel) { + const missing = []; + if (!token) missing.push("BHPKG_NOTIFY_TOKEN"); + if (!channel) missing.push("BHPKG_NOTIFY_CHANNEL"); + throw new Error(`缺少必要的环境变量以使用 notify 函数: ${missing.join(", ")}。请在白虎面板的任务设置中配置这些 Key。`); + } + + const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send'; + const cid = channelId || channel; + + if (!notifyUrl || !token || !cid) return; + + const parsedUrl = new URL(notifyUrl); + const protocol = parsedUrl.protocol === 'https:' ? https : http; + + const data = JSON.stringify({ + channel_id: cid, + title: title || '系统通知', + text: text + }); + + const options = { + hostname: parsedUrl.hostname, + port: parsedUrl.port, + path: parsedUrl.pathname + (parsedUrl.search || ''), + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'notify-token': token, + 'Content-Length': Buffer.byteLength(data) + } + }; + + const req = protocol.request(options); + req.on('error', (e) => {}); + req.write(data); + req.end(); +} + +module.exports = { notify }; diff --git a/builtin/nodejs/task.js b/builtin/nodejs/task.js new file mode 100644 index 0000000..93cefe5 --- /dev/null +++ b/builtin/nodejs/task.js @@ -0,0 +1,170 @@ +const http = require('http'); +const https = require('https'); +const { URL } = require('url'); + +/** + * 内部 API 请求辅助函数 + */ +function request(urlStr, method = 'GET', data = null) { + const token = process.env.BHPKG_OPENAPI_TOKEN || process.env.OPENAPI_TOKEN || process.env.BHPKG_NOTIFY_TOKEN; + if (!token) { + throw new Error("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量,无法使用任务管理操作"); + } + + const parsedUrl = new URL(urlStr); + const protocol = parsedUrl.protocol === 'https:' ? https : http; + + let payload = ''; + const headers = { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${token}` + }; + + if (data !== null) { + payload = JSON.stringify(data); + headers['Content-Length'] = Buffer.byteLength(payload); + } + + const options = { + hostname: parsedUrl.hostname, + port: parsedUrl.port, + path: parsedUrl.pathname + (parsedUrl.search || ''), + method: method, + headers: headers + }; + + return new Promise((resolve, reject) => { + const req = protocol.request(options, (res) => { + let body = ''; + res.setEncoding('utf8'); + res.on('data', (chunk) => body += chunk); + res.on('end', () => { + if (res.statusCode >= 200 && res.statusCode < 300) { + try { + resolve(body ? JSON.parse(body) : {}); + } catch (e) { + resolve(body); + } + } else { + let errMsg = body; + try { + const parsed = JSON.parse(body); + errMsg = parsed.msg || parsed.message || body; + } catch(e) {} + reject(new Error(`请求失败 [${res.statusCode}]: ${errMsg}`)); + } + }); + }); + + req.on('error', (e) => reject(e)); + if (payload) { + req.write(payload); + } + req.end(); + }); +} + +function getBaseUrl() { + const url = process.env.BHPKG_OPENAPI_URL || process.env.OPENAPI_URL; + if (url) { + if (url.endsWith('/env')) return url.slice(0, -4); + if (url.endsWith('/env/')) return url.slice(0, -5); + return url; + } + + const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send'; + const targets = ['/api/v1/notify/send/', '/api/v1/notify/send', '/api/v1/notify/', '/api/v1/notify']; + for (const target of targets) { + if (notifyUrl.includes(target)) { + return notifyUrl.replace(target, '/open2api/v1'); + } + } + return 'http://localhost:8052/open2api/v1'; +} + +/** + * 获取全部任务列表 + */ +async function getTasks() { + const url = `${getBaseUrl()}/tasks`; + const res = await request(url, 'GET'); + return res.data || []; +} + +/** + * 根据 ID 获取单个任务信息 + */ +async function getTask(id) { + const url = `${getBaseUrl()}/tasks/${id}`; + const res = await request(url, 'GET'); + return res.data; +} + +/** + * 根据 ID 更新指定任务 + */ +async function updateTask(id, name, command, remark, pin_type, trigger_type, schedule, timeout, work_dir, retry_count, retry_interval, random_range, enabled) { + const url = `${getBaseUrl()}/tasks/${id}`; + const payload = {}; + if (name !== undefined) payload.name = name; + if (command !== undefined) payload.command = command; + if (remark !== undefined) payload.remark = remark; + if (pin_type !== undefined) payload.pin_type = pin_type; + if (trigger_type !== undefined) payload.trigger_type = trigger_type; + if (schedule !== undefined) payload.schedule = schedule; + if (timeout !== undefined) payload.timeout = timeout; + if (work_dir !== undefined) payload.work_dir = work_dir; + if (retry_count !== undefined) payload.retry_count = retry_count; + if (retry_interval !== undefined) payload.retry_interval = retry_interval; + if (random_range !== undefined) payload.random_range = random_range; + if (enabled !== undefined) payload.enabled = enabled; + + const res = await request(url, 'PUT', payload); + return res.data; +} + +/** + * 根据 ID 删除任务 + */ +async function deleteTask(id) { + const url = `${getBaseUrl()}/tasks/${id}`; + await request(url, 'DELETE'); + return true; +} + +/** + * 触发运行指定任务 + */ +async function executeTask(id) { + const url = `${getBaseUrl()}/execute/task/${id}`; + const res = await request(url, 'POST'); + return res.data; +} + +/** + * 根据日志 ID 停止正在运行的任务 + */ +async function stopTask(logId) { + const url = `${getBaseUrl()}/tasks/stop/${logId}`; + const res = await request(url, 'POST'); + return res.data; +} + +/** + * 获取最近的任务执行结果列表 + */ +async function getLastResults() { + const url = `${getBaseUrl()}/execute/results`; + const res = await request(url, 'GET'); + return res.data || []; +} + +module.exports = { + getTasks, + getTask, + updateTask, + deleteTask, + executeTask, + stopTask, + getLastResults +}; diff --git a/builtin/python/baihu/__init__.py b/builtin/python/baihu/__init__.py index a3f9776..a271645 100644 --- a/builtin/python/baihu/__init__.py +++ b/builtin/python/baihu/__init__.py @@ -1,5 +1,23 @@ import os from .notify import notify as _notify +from .env import ( + get_envs, + get_env, + add_envs, + add_env, + update_env, + delete_envs, + delete_env +) +from .task import ( + get_tasks, + get_task, + update_task, + delete_task, + execute_task, + stop_task, + get_last_results +) def notify(title, text): """ @@ -19,4 +37,20 @@ def notify(title, text): return _notify(title, text) -__all__ = ['notify'] +__all__ = [ + 'notify', + 'get_envs', + 'get_env', + 'add_envs', + 'add_env', + 'update_env', + 'delete_envs', + 'delete_env', + 'get_tasks', + 'get_task', + 'update_task', + 'delete_task', + 'execute_task', + 'stop_task', + 'get_last_results' +] diff --git a/builtin/python/baihu/env.py b/builtin/python/baihu/env.py new file mode 100644 index 0000000..4fc1de9 --- /dev/null +++ b/builtin/python/baihu/env.py @@ -0,0 +1,129 @@ +import os +import json +import urllib.request +import urllib.error + +def _get_headers(): + token = os.environ.get("BHPKG_OPENAPI_TOKEN") or os.environ.get("OPENAPI_TOKEN") or os.environ.get("BHPKG_NOTIFY_TOKEN") + if not token: + raise RuntimeError("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量,无法使用环境管理操作") + return { + "Content-Type": "application/json", + "Authorization": f"Bearer {token}" + } + +def _get_envs_url(): + url = os.environ.get("BHPKG_OPENAPI_URL") or os.environ.get("OPENAPI_URL") + if url: + return url + + notify_url = os.environ.get("BHPKG_NOTIFY_URL", "http://localhost:8052/api/v1/notify/send") + for target in ["/api/v1/notify/send/", "/api/v1/notify/send", "/api/v1/notify/", "/api/v1/notify"]: + if target in notify_url: + return notify_url.replace(target, "/open2api/v1/env") + + return "http://localhost:8052/open2api/v1/env" + +def _request(url, method="GET", data=None): + headers = _get_headers() + payload = None + if data is not None: + payload = json.dumps(data).encode("utf-8") + + req = urllib.request.Request(url, data=payload, headers=headers, method=method) + try: + with urllib.request.urlopen(req) as resp: + body = resp.read().decode("utf-8") + if not body: + return {} + return json.loads(body) + except urllib.error.HTTPError as e: + err_body = e.read().decode("utf-8") + try: + err_json = json.loads(err_body) + msg = err_json.get("msg") or err_json.get("message") or err_body + except Exception: + msg = err_body + raise RuntimeError(f"请求失败 [{e.code}]: {msg}") + except Exception as e: + raise RuntimeError(f"请求发生异常: {e}") + +def get_envs(): + """ + 获取所有的环境变量列表。 + """ + url = f"{_get_envs_url()}/all" + res = _request(url, "GET") + return res.get("data", []) + +def get_env(name): + """ + 根据变量名获取环境变量。如果不存在则返回 None。 + """ + envs = get_envs() + for env in envs: + if env.get("name") == name: + return env + return None + +def add_envs(envs_list): + """ + 批量添加环境变量。 + envs_list: 包含环境变量字典的列表,如 [{"name": "KEY", "value": "VAL", "remark": "备注"}] + """ + url = _get_envs_url() + added_envs = [] + for env in envs_list: + if "name" not in env or "value" not in env: + raise ValueError("环境变量必须包含 'name' 和 'value'") + res = _request(url, "POST", env) + if "data" in res: + added_envs.append(res["data"]) + return added_envs + +def add_env(name, value, remark="", type="normal", hidden=True, enabled=True): + """ + 添加单个环境变量。 + """ + url = _get_envs_url() + payload = { + "name": name, + "value": value, + "remark": remark, + "type": type, + "hidden": hidden, + "enabled": enabled + } + res = _request(url, "POST", payload) + return res.get("data") + +def update_env(id, name, value, remark=None, type=None, hidden=None, enabled=None): + """ + 根据 ID 更新环境变量。 + """ + url = f"{_get_envs_url()}/{id}" + payload = {} + if name is not None: payload["name"] = name + if value is not None: payload["value"] = value + if remark is not None: payload["remark"] = remark + if type is not None: payload["type"] = type + if hidden is not None: payload["hidden"] = hidden + if enabled is not None: payload["enabled"] = enabled + + res = _request(url, "PUT", payload) + return res.get("data") + +def delete_envs(ids): + """ + 批量删除环境变量。 + """ + for fid in ids: + delete_env(fid) + +def delete_env(id): + """ + 根据 ID 删除指定的环境变量。 + """ + url = f"{_get_envs_url()}/{id}" + _request(url, "DELETE") + return True diff --git a/builtin/python/baihu/task.py b/builtin/python/baihu/task.py new file mode 100644 index 0000000..8502654 --- /dev/null +++ b/builtin/python/baihu/task.py @@ -0,0 +1,124 @@ +import os +import json +import urllib.request +import urllib.error + +def _get_headers(): + token = os.environ.get("BHPKG_OPENAPI_TOKEN") or os.environ.get("OPENAPI_TOKEN") or os.environ.get("BHPKG_NOTIFY_TOKEN") + if not token: + raise RuntimeError("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量,无法使用任务管理操作") + return { + "Content-Type": "application/json", + "Authorization": f"Bearer {token}" + } + +def _get_base_url(): + url = os.environ.get("BHPKG_OPENAPI_URL") or os.environ.get("OPENAPI_URL") + if url: + # If openapi_url ends with /env, replace it with nothing or use base + if url.endswith("/env"): + return url[:-4] + elif url.endswith("/env/"): + return url[:-5] + return url + + notify_url = os.environ.get("BHPKG_NOTIFY_URL", "http://localhost:8052/api/v1/notify/send") + for target in ["/api/v1/notify/send/", "/api/v1/notify/send", "/api/v1/notify/", "/api/v1/notify"]: + if target in notify_url: + return notify_url.replace(target, "/open2api/v1") + + return "http://localhost:8052/open2api/v1" + +def _request(url, method="GET", data=None): + headers = _get_headers() + payload = None + if data is not None: + payload = json.dumps(data).encode("utf-8") + + req = urllib.request.Request(url, data=payload, headers=headers, method=method) + try: + with urllib.request.urlopen(req) as resp: + body = resp.read().decode("utf-8") + if not body: + return {} + return json.loads(body) + except urllib.error.HTTPError as e: + err_body = e.read().decode("utf-8") + try: + err_json = json.loads(err_body) + msg = err_json.get("msg") or err_json.get("message") or err_body + except Exception: + msg = err_body + raise RuntimeError(f"请求失败 [{e.code}]: {msg}") + except Exception as e: + raise RuntimeError(f"请求发生异常: {e}") + +def get_tasks(): + """ + 获取全部任务列表。 + """ + url = f"{_get_base_url()}/tasks" + res = _request(url, "GET") + return res.get("data", []) + +def get_task(id): + """ + 根据 ID 获取单个任务的详细信息。 + """ + url = f"{_get_base_url()}/tasks/{id}" + res = _request(url, "GET") + return res.get("data") + +def update_task(id, name=None, command=None, remark=None, pin_type=None, trigger_type=None, schedule=None, timeout=None, work_dir=None, retry_count=None, retry_interval=None, random_range=None, enabled=None): + """ + 根据 ID 更新任务。 + """ + url = f"{_get_base_url()}/tasks/{id}" + payload = {} + if name is not None: payload["name"] = name + if command is not None: payload["command"] = command + if remark is not None: payload["remark"] = remark + if pin_type is not None: payload["pin_type"] = pin_type + if trigger_type is not None: payload["trigger_type"] = trigger_type + if schedule is not None: payload["schedule"] = schedule + if timeout is not None: payload["timeout"] = timeout + if work_dir is not None: payload["work_dir"] = work_dir + if retry_count is not None: payload["retry_count"] = retry_count + if retry_interval is not None: payload["retry_interval"] = retry_interval + if random_range is not None: payload["random_range"] = random_range + if enabled is not None: payload["enabled"] = enabled + + res = _request(url, "PUT", payload) + return res.get("data") + +def delete_task(id): + """ + 根据 ID 删除指定任务。 + """ + url = f"{_get_base_url()}/tasks/{id}" + _request(url, "DELETE") + return True + +def execute_task(id): + """ + 触发执行特定任务。 + """ + url = f"{_get_base_url()}/execute/task/{id}" + res = _request(url, "POST") + return res.get("data") + +def stop_task(log_id): + """ + 根据日志 ID 停止正在运行的任务。 + """ + url = f"{_get_base_url()}/tasks/stop/{log_id}" + res = _request(url, "POST") + return res.get("data") + +def get_last_results(): + """ + 获取最近的执行结果列表。 + """ + url = f"{_get_base_url()}/execute/results" + res = _request(url, "GET") + return res.get("data", []) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index cdde3f3..ee0cbdd 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -43,7 +43,7 @@ export default defineConfig({ link: '/guide/examples/', items: [ { text: '浏览器示例', link: '/guide/examples/browser' }, - { text: '消息通知示例', link: '/guide/examples/notify' } + { text: '内置库示例', link: '/guide/examples/builtin' } ] } ] diff --git a/docs/guide/examples/builtin.md b/docs/guide/examples/builtin.md new file mode 100644 index 0000000..dc884f3 --- /dev/null +++ b/docs/guide/examples/builtin.md @@ -0,0 +1,296 @@ +# 内置库示例 + +白虎面板提供了一个名为 `baihu` 的内建包(Built-in SDK),支持 Python 和 Node.js。通过该内置库,您可以在脚本中实现**消息推送**、**环境变量管理**以及**任务执行控制**等高级功能。 + +--- + +## 准备工作 + +在运行内置库脚本之前,请确保完成了以下步骤: + +### 1. 安装内置包 +在白虎面板的「终端」页面中,或者通过创建临时任务执行以下命令,为面板管理的所有语言环境安装 `baihu` 包: + +```bash +baihu builtininstall +``` + +### 2. 配置环境变量 +根据您需要调用的功能,在定时任务的“环境变量”或“机密”中配置以下对应 Key: + +#### 消息推送所需环境变量 +- **`BHPKG_NOTIFY_TOKEN`**:进入「消息推送」->「脚本调用说明」页面即可找到。 +- **`BHPKG_NOTIFY_CHANNEL`**:进入「消息推送」->「渠道列表」页面,查看对应渠道的 **ID**。 +- **`BHPKG_NOTIFY_URL`** (可选):默认为 `http://localhost:8052/api/v1/notify/send`。如果修改了主服务端口,需要同步修改。 + +#### 环境变量管理与定时任务控制所需环境变量 +- **`BHPKG_OPENAPI_TOKEN`** (或 `OPENAPI_TOKEN`):用于 OpenAPI 接口鉴权,进入「系统设置」->「OpenAPI」页面,生成并复制 Token。 +- **`BHPKG_OPENAPI_URL`** (或 `OPENAPI_URL`,可选):默认为本地面板 API 地址。若在非标准环境下运行,可手动指定(例如 `http://localhost:8052`)。 + +--- + +## 消息通知示例 + +只需要一行代码即可触发零配置推送。 + +::: code-group + +```python [Python] +import baihu + +def main(): + print("正在尝试发送 Python 内建通知...") + try: + # 调用内置 notify 函数 + # 内部会自动使用环境变量进行鉴权和投递 + response = baihu.notify( + title="Python 任务提醒", + text="这是一条来自 Python 示例脚本的通知消息。调用非常简单!" + ) + print("发送请求已处理。") + if response: + print(f"服务器响应: {response}") + + except Exception as e: + print(f"发送过程发生异常: {e}") + +if __name__ == "__main__": + main() +``` + +```javascript [Node.js] +const baihu = require('baihu'); + +console.log("正在尝试发送 Node.js 内建通知..."); + +try { + // 简单的一行代码即可完成推送,内置包采用异步非阻塞发送 + baihu.notify( + "Node.js 任务提醒", + "这是一条来自 Node.js 示例脚本的通知消息。无需配置 API 地址或 Token。" + ); + console.log("发送请求已提交。"); + +} catch (e) { + console.error(`通知失败: ${e.message}`); +} +``` + +::: + +--- + +## 环境变量管理 + +内置库支持对面板的环境变量进行增删改查。 + +### 支持方法 + +* **Python**: + - `get_envs()`: 获取所有环境变量列表。 + - `get_env(name)`: 根据变量名称获取详情。 + - `add_env(name, value, remark)`: 添加新的环境变量。 + - `update_env(id, name, value, remark)`: 更新指定 ID 的环境变量值。 + - `delete_env(id)`: 根据 ID 删除环境变量。 +* **Node.js**: + - `getEnvs()`: 获取所有环境变量列表。 + - `getEnv(name)`: 根据变量名称获取详情。 + - `addEnv(name, value, remark)`: 添加新的环境变量。 + - `updateEnv(id, name, value, remark)`: 更新指定 ID 的环境变量值。 + - `deleteEnv(id)`: 根据 ID 删除环境变量。 + +### 代码示例 + +::: code-group + +```python [Python] +import baihu + +def main(): + print("====== 开始运行 Python 环境变量管理示例 ======") + try: + # 1. 获取全部环境变量 + envs = baihu.get_envs() + print(f"当前共有 {len(envs)} 个环境变量") + + # 2. 新增一个临时环境变量 + new_env_name = "BHPKG_TEST_KEY" + new_env_val = "HelloBaihu" + print(f"正在创建环境变量: {new_env_name}...") + created_env = baihu.add_env( + name=new_env_name, + value=new_env_val, + remark="Python SDK 测试自动创建" + ) + print(f"创建成功: ID={created_env.get('id')}, Name={created_env.get('name')}") + + # 3. 查询刚才创建的环境变量详情 + checked_env = baihu.get_env(new_env_name) + if checked_env: + print(f"成功查询到变量: {checked_env.get('name')} = {checked_env.get('value')}") + + # 4. 修改该环境变量的值 + updated_val = "HelloBaihu_Updated" + print(f"正在修改环境变量的值为: {updated_val}...") + updated_env = baihu.update_env( + id=checked_env.get("id"), + name=new_env_name, + value=updated_val, + remark="Python SDK 测试自动更新" + ) + print(f"更新成功: Value={updated_env.get('value')}") + + # 5. 删除该临时环境变量 + print(f"正在删除临时环境变量: ID={checked_env.get('id')}...") + baihu.delete_env(checked_env.get("id")) + print("删除成功!") + + except Exception as e: + print(f"环境变量操作失败: {e}") + print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。") + +if __name__ == "__main__": + main() +``` + +```javascript [Node.js] +const baihu = require('baihu'); + +async function main() { + console.log("====== 开始运行 Node.js 环境变量管理示例 ======"); + try { + // 1. 获取全部环境变量 + const envs = await baihu.getEnvs(); + console.log(`当前共有 ${envs.length} 个环境变量`); + + // 2. 新增一个临时环境变量 + const newEnvName = "BHPKG_TEST_KEY_JS"; + const newEnvVal = "HelloBaihuJS"; + console.log(`正在创建环境变量: ${newEnvName}...`); + const createdEnv = await baihu.addEnv( + newEnvName, + newEnvVal, + "Node.js SDK 测试自动创建" + ); + console.log(`创建成功: ID={createdEnv.id}, Name={createdEnv.name}`); + + // 3. 查询该环境变量 + const checkedEnv = await baihu.getEnv(newEnvName); + if (checkedEnv) { + console.log(`成功查询到变量: ${checkedEnv.name} = ${checkedEnv.value}`); + + // 4. 修改该环境变量的值 + const updatedVal = "HelloBaihuJS_Updated"; + console.log(`正在修改环境变量的值为: ${updatedVal}...`); + const updatedEnv = await baihu.updateEnv( + checkedEnv.id, + newEnvName, + updatedVal, + "Node.js SDK 测试自动更新" + ); + console.log(`更新成功: Value=${updatedEnv.value}`); + + // 5. 删除该临时环境变量 + console.log(`正在删除临时环境变量: ID={checkedEnv.id}...`); + await baihu.deleteEnv(checkedEnv.id); + console.log("删除成功!"); + } + + } catch (e) { + console.error(`环境变量操作失败: ${e.message}`); + console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。"); + } +} + +main(); +``` + +::: + +--- + +## 定时任务管理与控制 + +内置库支持查询面板的任务列表、最近的执行结果以及手动触发特定任务的运行。 + +### 支持方法 + +* **Python**: + - `get_tasks()`: 获取所有定时任务列表。 + - `execute_task(id)`: 立即触发指定 ID 任务的运行。 + - `get_last_results()`: 获取最近任务的执行记录。 +* **Node.js**: + - `getTasks()`: 获取所有定时任务列表。 + - `executeTask(id)`: 立即触发指定 ID 任务的运行。 + - `getLastResults()`: 获取最近任务的执行记录。 + +### 代码示例 + +::: code-group + +```python [Python] +import baihu + +def main(): + print("====== 开始运行 Python 任务管理与执行控制示例 ======") + try: + # 1. 获取所有任务列表 + tasks = baihu.get_tasks() + print(f"成功获取到 {len(tasks)} 个定时任务:") + for task in tasks[:5]: # 仅打印前5个 + print(f" - [{task.get('id')}] {task.get('name')} (表达式: {task.get('schedule')}, 备注: {task.get('remark')})") + + # 2. 尝试触发第一个任务的运行 + if tasks: + target_task = tasks[0] + print(f"\n尝试手动触发任务运行: [{target_task.get('id')}] {target_task.get('name')}...") + baihu.execute_task(target_task.get("id")) + print("执行指令发送成功。") + + # 3. 获取最近的执行结果列表 + results = baihu.get_last_results() + print(f"\n最近共有 {len(results)} 条任务执行记录。") + + except Exception as e: + print(f"任务操作失败: {e}") + print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。") + +if __name__ == "__main__": + main() +``` + +```javascript [Node.js] +const baihu = require('baihu'); + +async function main() { + console.log("====== 开始运行 Node.js 任务管理与执行控制示例 ======"); + try { + // 1. 获取所有任务列表 + const tasks = await baihu.getTasks(); + console.log(`成功获取到 ${tasks.length} 个定时任务:`); + tasks.slice(0, 5).forEach(task => { // 仅展示前5项 + console.log(` - [${task.id}] ${task.name} (表达式: ${task.schedule || ''}, 备注: ${task.remark || ''})`); + }); + + // 2. 尝试触发第一个任务的运行 + if (tasks.length > 0) { + const targetTask = tasks[0]; + console.log(`\n尝试手动触发任务运行: [${targetTask.id}] ${targetTask.name}...`); + await baihu.executeTask(targetTask.id); + console.log("执行指令发送成功。"); + } + + // 3. 获取最近的执行结果列表 + const results = await baihu.getLastResults(); + console.log(`\n最近共有 ${results.length} 条任务执行记录。`); + + } catch (e) { + console.error(`任务操作失败: ${e.message}`); + console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。"); + } +} + +main(); +``` + +::: diff --git a/docs/guide/examples/index.md b/docs/guide/examples/index.md index e5c793b..eb9a0b8 100644 --- a/docs/guide/examples/index.md +++ b/docs/guide/examples/index.md @@ -23,5 +23,4 @@ example/ 目前文档已经整理出的示例类型: - [浏览器示例](./browser.md) - -后面如果继续增加 HTTP、数据库、通知推送等示例,也会按这个目录结构继续扩展。 +- [内置库示例](./builtin.md) diff --git a/docs/guide/examples/notify.md b/docs/guide/examples/notify.md deleted file mode 100644 index bdb0a74..0000000 --- a/docs/guide/examples/notify.md +++ /dev/null @@ -1,87 +0,0 @@ -# 消息通知示例 - -白虎面板提供了一个名为 `baihu` 的内建包,让您可以在脚本(Python 或 Node.js)中通过一行代码实现零配置推送。 - ---- - -## 准备工作 - -在运行消息通知脚本之前,请确保已经完成了必要的初始化工作。 - -### 1. 安装内建包 -在白虎面板的在线终端或通过任务执行以下命令,为您当前的所有语言环境安装 `baihu` 包: - -```bash -baihu builtininstall -``` - -### 2. 配置环境变量 -前往 **「定时任务」** -> **「编辑任务」** -> **「环境变量」**,添加以下两个键值对: - -- `BHPKG_NOTIFY_TOKEN`: 进入「消息推送」->「脚本调用说明」标签即可找到。 -- `BHPKG_NOTIFY_CHANNEL`: 进入「消息推送」->「渠道列表」标签即可查看对应的 **ID**。 - -> [!TIP] -> 如果您更改了容器内部的服务端口(默认 8052),还需要额外添加 `BHPKG_NOTIFY_URL` 变量。详情请参考 [消息中心说明](../notify.md)。 - ---- - -## 代码示例 - -### Python (同步) - -```python -import baihu - -# 内建通知测试示例 (Python) -def main(): - print("正在尝试发送 Python 内建通知...") - try: - # 调用内建 notify 函数 - # 内部会自动使用环境变量进行鉴权和投递 - response = baihu.notify( - title="Python 任务提醒", - text="这是一条来自 Python 示例脚本的通知消息。调用非常简单!" - ) - print(f"服务器响应: {response}") - - except Exception as e: - print(f"发送过程发生异常: {e}") - -if __name__ == "__main__": - main() -``` - -### Node.js (异步) - -```javascript -const baihu = require('baihu'); - -/** - * 内建通知测试示例 (Node.js) - */ -console.log("正在尝试发送 Node.js 内建通知..."); - -try { - // 简单的一行代码即可完成推送 - baihu.notify( - "Node.js 任务提醒", - "这是一条来自 Node.js 示例脚本的通知消息。无需配置 API 地址或 Token。" - ); - - console.log("发送请求已提交。"); - console.log("提示:内建包采用异步非阻塞发送,不会干扰主逻辑执行。"); - -} catch (e) { - console.error(`通知失败: ${e.message}`); -} -``` - ---- - -## 运行与验证 - -1. **保存脚本**:将上述代码保存为 `.py` 或 `.js` 文件。 -2. **创建任务**:在面板中创建新任务并关联该文件。 -3. **注入配置**:在任务配置中填入 `BHPKG_NOTIFY_TOKEN` 等变量。 -4. **立即运行**:点击「运行」按钮,检查对应的消息渠道是否收到了推送消息。 diff --git a/docs/guide/notify.md b/docs/guide/notify.md index a4b92cd..8bbafd7 100644 --- a/docs/guide/notify.md +++ b/docs/guide/notify.md @@ -37,14 +37,17 @@ ### 路径二:脚本手动调用 (内置助手库 - 推荐) -白虎面板提供了一套**零配置**的内建助手库(Built-in SDK),支持 Python 和 Node.js。它会自动读取系统注入的环境变量,让您在脚本中只需一行代码即可实现通知投递。 +白虎面板提供了一套**零配置**的内建助手库(Built-in SDK),支持 Python 和 Node.js。除了支持极简的消息通知投递外,它还支持管理面板的**环境变量**与**定时任务控制**。 #### 1. 如何获取配置 Key? -在使用助手库前,请确保您已经在任务设置的“环境变量”或“机密”中配置了以下两个同名 Key: -- **BHPKG_NOTIFY_TOKEN**:进入「消息推送」->「脚本调用说明」标签,您可以直接复制此处的 Token(如未生成请先点击生成)。 -- **BHPKG_NOTIFY_CHANNEL**:进入「消息推送」->「渠道列表」标签,可以查看每个渠道对应的 **ID**。如果您希望使用默认渠道,也可直接在「脚本调用说明」页面的代码示例中找到默认 ID。 -- **BHPKG_NOTIFY_URL** (可选):内建通知 API 的地址。默认为 `http://localhost:8052/api/v1/notify/send`。**如果您更改了容器内部的服务监听端口(如通过 `BH_SERVER_PORT`),则需要同步设置此变量为 `http://localhost:{您的端口}/api/v1/notify/send`。** - +在使用助手库前,请确保您已经在任务设置的“环境变量”或“机密”中配置了以下对应 Key: +- **消息推送相关**: + - `BHPKG_NOTIFY_TOKEN`:进入「消息推送」->「脚本调用说明」标签,可以直接复制此处的 Token。 + - `BHPKG_NOTIFY_CHANNEL`:进入「消息推送」->「渠道列表」标签,可以查看每个渠道对应的 **ID**。 + - `BHPKG_NOTIFY_URL` (可选):内置通知 API 的地址。默认为 `http://localhost:8052/api/v1/notify/send`。 +- **环境与任务管理相关**: + - `BHPKG_OPENAPI_TOKEN` (或 `OPENAPI_TOKEN`):OpenAPI 鉴权 Token,在「系统设置」->「OpenAPI」中生成。 + - `BHPKG_OPENAPI_URL` (可选):默认为本地面板 API 地址。 #### 2. 环境初始化 在开始编写脚本前,您需要在终端执行以下命令,为面板管理的所有语言环境安装 `baihu` 包: @@ -54,24 +57,38 @@ baihu builtininstall ``` *该操作会将助手库安装到 mise 管理的所有版本中,确保 import 成功。* -#### 2. 代码示例 +#### 3. 代码示例 ##### Python (同步调用) ```python import baihu -# 内部自动通过环境变量鉴权,无需填 TOKEN 和 URL +# 消息通知 baihu.notify("任务标题", "通知正文内容") + +# 环境变量与任务管理(详细用法见内置库示例) +envs = baihu.get_envs() +tasks = baihu.get_tasks() ``` ##### Node.js (异步调用) ```javascript const baihu = require('baihu'); -// 极简调用,支持在 CommonJS/ESM 中使用 +// 消息通知 baihu.notify("任务标题", "通知正文内容"); + +// 环境变量与任务管理(详细用法见内置库示例) +(async () => { + const envs = await baihu.getEnvs(); + const tasks = await baihu.getTasks(); +})(); ``` +> [!TIP] +> 关于环境变量增删改查以及任务触发控制的完整 API 列表与更详尽的代码,请参考 [内置库示例](./examples/builtin.md)。 + + --- ### 路径三:其他语言/高级调用 (原始 API) diff --git a/example/builtin/test_env.js b/example/builtin/test_env.js new file mode 100644 index 0000000..a04fb79 --- /dev/null +++ b/example/builtin/test_env.js @@ -0,0 +1,58 @@ +const baihu = require('baihu'); + +/** + * 内建工具环境变量管理测试示例 (Node.js) + * + * 使用说明: + * 1. 确保已在该 Node.js 环境下安装过内建包。 + * 2. 运行时系统需要注入有效的 OpenAPI 凭证 (BHPKG_OPENAPI_TOKEN 或 OPENAPI_TOKEN)。 + */ + +async function main() { + console.log("====== 开始运行 Node.js 环境变量管理示例 ======"); + + try { + // 获取全部环境变量 + const envs = await baihu.getEnvs(); + console.log(`当前共有 ${envs.length} 个环境变量`); + + // 新增一个临时环境变量 + const newEnvName = "BHPKG_TEST_KEY_JS"; + const newEnvVal = "HelloBaihuJS"; + console.log(`正在创建环境变量: ${newEnvName}...`); + const createdEnv = await baihu.addEnv( + newEnvName, + newEnvVal, + "Node.js SDK 测试自动创建" + ); + console.log(`创建成功: ID=${createdEnv.id}, Name=${createdEnv.name}`); + + // 查询该环境变量 + const checkedEnv = await baihu.getEnv(newEnvName); + if (checkedEnv) { + console.log(`成功查询到变量: ${checkedEnv.name} = ${checkedEnv.value}`); + + // 修改该环境变量的值 + const updatedVal = "HelloBaihuJS_Updated"; + console.log(`正在修改环境变量的值为: ${updatedVal}...`); + const updatedEnv = await baihu.updateEnv( + checkedEnv.id, + newEnvName, + updatedVal, + "Node.js SDK 测试自动更新" + ); + console.log(`更新成功: Value=${updatedEnv.value}`); + + // 删除该临时环境变量 + console.log(`正在删除临时环境变量: ID=${checkedEnv.id}...`); + await baihu.deleteEnv(checkedEnv.id); + console.log("删除成功!"); + } + + } catch (e) { + console.error(`环境变量操作失败: ${e.message}`); + console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。"); + } +} + +main(); diff --git a/example/builtin/test_env.py b/example/builtin/test_env.py new file mode 100644 index 0000000..62f73cd --- /dev/null +++ b/example/builtin/test_env.py @@ -0,0 +1,55 @@ +import baihu + +# 内建工具环境变量管理测试示例 (Python) +# +# 前提条件: +# 1. 已经在环境中安装了 baihu 包(例如通过 `baihu builtininstall`) +# 2. 环境中已注入有效环境变量: +# - BHPKG_OPENAPI_TOKEN (必填,用于管理接口鉴权) + +def main(): + print("====== 开始运行 Python 环境变量管理示例 ======") + + try: + # 获取全部环境变量 + envs = baihu.get_envs() + print(f"当前共有 {len(envs)} 个环境变量") + + # 新增一个临时环境变量 + new_env_name = "BHPKG_TEST_KEY" + new_env_val = "HelloBaihu" + print(f"正在创建环境变量: {new_env_name}...") + created_env = baihu.add_env( + name=new_env_name, + value=new_env_val, + remark="Python SDK 测试自动创建" + ) + print(f"创建成功: ID={created_env.get('id')}, Name={created_env.get('name')}") + + # 查询刚才创建的环境变量详情 + checked_env = baihu.get_env(new_env_name) + if checked_env: + print(f"成功查询到变量: {checked_env.get('name')} = {checked_env.get('value')}") + + # 修改该环境变量的值 + updated_val = "HelloBaihu_Updated" + print(f"正在修改环境变量的值为: {updated_val}...") + updated_env = baihu.update_env( + id=checked_env.get("id"), + name=new_env_name, + value=updated_val, + remark="Python SDK 测试自动更新" + ) + print(f"更新成功: Value={updated_env.get('value')}") + + # 删除该临时环境变量 + print(f"正在删除临时环境变量: ID={checked_env.get('id')}...") + baihu.delete_env(checked_env.get("id")) + print("删除成功!") + + except Exception as e: + print(f"环境变量操作失败: {e}") + print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。") + +if __name__ == "__main__": + main() diff --git a/example/notify/test_notify.js b/example/builtin/test_notify.js similarity index 100% rename from example/notify/test_notify.js rename to example/builtin/test_notify.js diff --git a/example/notify/test_notify.py b/example/builtin/test_notify.py similarity index 100% rename from example/notify/test_notify.py rename to example/builtin/test_notify.py diff --git a/example/builtin/test_task.js b/example/builtin/test_task.js new file mode 100644 index 0000000..da33157 --- /dev/null +++ b/example/builtin/test_task.js @@ -0,0 +1,40 @@ +const baihu = require('baihu'); + +/** + * 内建工具任务管理测试示例 (Node.js) + * + * 使用说明: + * 1. 确保已在该 Node.js 环境下安装过内建包。 + * 2. 运行时系统需要注入有效的 OpenAPI 凭证 (BHPKG_OPENAPI_TOKEN 或 OPENAPI_TOKEN)。 + */ + +async function main() { + console.log("====== 开始运行 Node.js 任务管理与执行控制示例 ======"); + + try { + // 获取所有任务列表 + const tasks = await baihu.getTasks(); + console.log(`成功获取到 ${tasks.length} 个定时任务:`); + tasks.slice(0, 5).forEach(task => { // 仅展示前5项 + console.log(` - [${task.id}] ${task.name} (表达式: ${task.schedule || ''}, 备注: ${task.remark || ''})`); + }); + + // 尝试触发第一个任务的运行 + if (tasks.length > 0) { + const targetTask = tasks[0]; + console.log(`\n尝试手动触发任务运行: [${targetTask.id}] ${targetTask.name}...`); + await baihu.executeTask(targetTask.id); + console.log("执行指令发送成功。"); + } + + // 获取最近的执行结果列表 + const results = await baihu.getLastResults(); + console.log(`\n最近共有 ${results.length} 条任务执行记录。`); + + } catch (e) { + console.error(`任务操作失败: ${e.message}`); + console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。"); + } +} + +main(); diff --git a/example/builtin/test_task.py b/example/builtin/test_task.py new file mode 100644 index 0000000..2e98741 --- /dev/null +++ b/example/builtin/test_task.py @@ -0,0 +1,36 @@ +import baihu + +# 内建工具任务管理与执行控制测试示例 (Python) +# +# 前提条件: +# 1. 已经在环境中安装了 baihu 包(例如通过 `baihu builtininstall`) +# 2. 环境中已注入有效环境变量: +# - BHPKG_OPENAPI_TOKEN (必填,用于管理接口鉴权) + +def main(): + print("====== 开始运行 Python 任务管理与执行控制示例 ======") + + try: + # 获取所有任务列表 + tasks = baihu.get_tasks() + print(f"成功获取到 {len(tasks)} 个定时任务:") + for task in tasks[:5]: # 仅打印前5个 + print(f" - [{task.get('id')}] {task.get('name')} (表达式: {task.get('schedule')}, 备注: {task.get('remark')})") + + # 示例:尝试触发第一个任务的运行 + if tasks: + target_task = tasks[0] + print(f"\n尝试手动触发任务运行: [{target_task.get('id')}] {target_task.get('name')}...") + result = baihu.execute_task(target_task.get("id")) + print("执行指令发送成功。") + + # 获取最近的执行结果列表 + results = baihu.get_last_results() + print(f"\n最近共有 {len(results)} 条任务执行记录。") + + except Exception as e: + print(f"任务操作失败: {e}") + print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。") + +if __name__ == "__main__": + main()