ODS Host Agent API 完整指南容器外如何安全管理宿主服务与 .env 写入【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODSODS 是一款把 PC、Mac 或 Linux 变成AI 服务器的开源项目LLM 推理、聊天 UI、语音、Agent、工作流、RAG 与图像生成。而ODS Host Agent宿主代理服务是其中一块常被忽略的关键机制它以轻量 HTTP 服务运行在宿主机上Docker 容器之外让运行在容器里的 Dashboard API 能够安全地管理宿主服务和写入 .env 文件同时避免了直接挂载 Docker socket 的巨大安全隐患。为什么需要 Host AgentDashboard API 跑在 Docker 容器内无法直接执行宿主机的docker compose命令。传统做法是把 Docker socket 挂进容器——但这等于把宿主机的 Docker 控制权整个交给了容器风险极高。ODS 的解法就是 Host Agent️ 一个运行在宿主机上的轻量 HTTP 服务纯 Python 标准库实现 监听ODS_AGENT_BIND:ODS_AGENT_PORT默认端口7710 只接受带Bearer API Key的认证请求 代表容器执行docker compose启停、日志拉取等操作结果容器永远接触不到 Docker socket所有宿主操作都被收敛到一个有鉴权、有校验、有限时的窄边界上。各平台如何启动 Host Agent 安装过程中就会自动启动三种平台机制不同平台启动机制 Linuxsystemd 用户服务 macOS由 macOS 安装器启动 Windows由安装器启动经ods.ps1管理Linux 上会自动探测ods-network网关让容器可以访问到 Agent探测失败则回退到默认 Docker 桥接网关最后回退127.0.0.1。macOS 和 Windows 默认只绑定127.0.0.1。除非显式配置ODS_AGENT_BIND否则绝不会绑定0.0.0.0。快速配置关键 .env 变量一览表 ⚙️Agent 的配置全部来自 ODS 安装目录下的.env文件变量默认值说明ODS_AGENT_KEY无请求鉴权用的 API Key缺省时回退DASHBOARD_API_KEYODS_AGENT_BIND按平台绑定地址macOS/Windows 为127.0.0.1ODS_AGENT_PORT7710Agent 监听端口GPU_BACKENDnvidia构建 compose 栈时传入的 GPU 后端TIER1硬件档位参与 compose 栈解析ODS_DATA_DIR~/.ods数据目录根路径ODS_USER_EXTENSIONS_DIR$ODS_DATA_DIR/user-extensions用户扩展目录此外 Agent 还会加载 core-service-ids.json 来确定哪些核心服务受保护、不可被托管操作如 dashboard-api、llama-server 等若该文件缺失会启用内置的硬编码兜底清单防止配置丢失 防护失效。容器如何调用 Host Agent调用链路非常清晰见 host_agent_client.pyDashboard API 由ODS_AGENT_HOSTODS_AGENT_PORT拼出AGENT_URL容器通过 Docker 的host.docker.internalDNS 名称访问宿主机上的 Agent每个请求携带Authorization: Bearer ODS_AGENT_KEY头除/health健康检查外所有/v1/*接口都强制鉴权且使用恒定时间比较防止时序攻击⚡ 一个贴心的细节当宿主 Agent 不可达时安装/启用/禁用操作仍会在文件层面成功并返回restart_required: true提示执行ods restart完成重启。.env 安全写入/v1/env/update端点详解 ✍️这是 Host Agent 最有价值的能力之一。容器内挂载的.env是只读的——只有宿主上的 Agent 能写密钥到磁盘。Dashboard 的保存设置功能正是委托给它完成的实现见 ods-host-agent.py 中的_handle_env_update。写入前的校验相当严格✅ 请求体上限64 KB普通接口仅 16 KB因为.env文件通常更大✅ 逐行校验KEYvalue格式key 必须匹配环境变量命名规范✅ 所有 key 对照 .env.schema.json 做白名单校验扩展引入的额外 key 会被记录但宽容接受✅ 特殊场景下自动强制写入必需项如代理模式下强制WEBUI_AUTHtrue 写入前自动备份原文件可回滚换句话说即使你在网页面板里误改了配置也有一道宿主机端的最后防线替你把关。️扩展容器管理启动、停止与日志 /v1/*还覆盖了完整的扩展生命周期操作端点作用POST /v1/extension/start启动扩展容器自动预创建./data/卷目录并修正属主POST /v1/extension/stop停止扩展容器POST /v1/extension/logs拉取最近日志tail限制在 1–500 行POST /v1/extension/install/hooks扩展安装与生命周期钩子GET /v1/service/health容器生命周期 健康检查快照GET /v1/gpu/metrics/GET /v1/llm/status宿主机 GPU 指标与推理状态Docker Desktop 拿不到的数据启动操作前会先做三重验证service_id正则合法 → 不是核心服务 → 在user-extensions/中存在且 manifest 有效再叠加每服务锁防止并发启停竞争子进程 120 秒超时兜底。安全边界速览为什么要读这篇把 Host Agent 理解成宿主机上唯一的受控闸门最贴切。它同时具备网络边界默认仅回环/内网可达绝不暴露公网鉴权边界所有变更接口必须携带 API Key核心服务保护核心服务 ID 拒绝托管操作403输入校验service ID 正则 schema 白名单 请求体大小限制⏱️超时兜底Docker 操作 120s 超时、日志 5s 超时延伸阅读与关键文件 文件说明ods/docs/HOST-AGENT-API.md完整的官方 API 参考文档ods/bin/ods-host-agent.pyHost Agent 完整实现源码ods/scripts/systemd/ods-host-agent.serviceLinux systemd 服务模板ods/extensions/services/dashboard-api/host_agent_client.py容器侧的带重试 HTTP 客户端ods/.env.example全部.env变量示例ods/.env.schema.json.env写入白名单 schema一句话总结ODS 用 Host Agent 把容器管理宿主机这件高风险的事做成了有鉴权、有校验、有备份、有时限的标准化 API——这正是它值得学习的地方。【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考