Onevium service demo

> 内容来源：Onevium 官方文档
> 文章: 管理开发服务
> 原文: https://onevium.com/zh/docs/managed-services
> 语言：简体中文
> 更新于: 2026-09-09
> 适用版本: 1.1.22
> 功能状态: 已发布

---

# 管理开发服务

通过对话启动项目预览，检查进程、端口就绪、日志，并管理停止与重启。

## 用托管服务运行本地预览

网站预览、API 等需要持续运行的进程，可以交给 Onevium 的托管服务管理。它记录服务名称、启动命令、目录、进程和端口，并提供对应服务的停止与重启操作。

在对话中明确说“作为托管开发服务启动”。普通终端命令、`nohup` 或一次后台构建不等于托管服务。

## 准备一个最小演示项目

本例只需要本机已经安装 **Node.js**，不需要 `npm install` 或下载第三方项目。先在终端运行：

```bash
node --version
```

如果命令不可用，先准备 Node.js 运行环境再继续；Onevium 内部使用的运行时不等于终端里一定有 `node`。

按[项目教程](https://onevium.com/zh/docs/projects-and-sessions#prerequisites)新建 `onevium-service-demo`。在这个空项目中，让 Agent 创建 `server.mjs`，完整内容如下：

```javascript
import { createServer } from "node:http";

const port = 4173;
const html = `<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Onevium service demo</title>
<h1>Onevium service demo</h1>
<p>The local preview is ready.</p>
</html>`;

createServer((request, response) => {
  console.log(`${new Date().toISOString()} ${request.method} ${request.url}`);
  response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
  response.end(html);
}).listen(port, "127.0.0.1", () => {
  console.log(`READY http://127.0.0.1:${port}`);
});
```

先只创建文件，不在普通终端后台启动它。这个示例只监听本机回环地址；本地预览不是公网部署。

## 启动演示服务

在同一项目的会话发送：

```text
先列出现有托管服务，检查是否已有本项目的演示服务。
若没有，确认本项目 server.mjs 已保存，且 4173 端口未被占用。
将 node server.mjs 作为托管开发服务启动：
名称 onevium-service-demo，工作目录使用本项目的绝对路径，
日志就绪标记为 READY，自动重启策略为 no。
不要停止其他进程；端口被占用时先报告并等待处理。
返回服务 ID、进程、端口和就绪状态，并打开本地预览。
```

这个请求应调用 Onevium 的 `run_service` 能力，而不是只把启动命令写进回答。如果需要确认权限，核对命令是 `node server.mjs`，目录是刚创建的演示项目。

预期地址为 `http://127.0.0.1:4173`。需要再次打开时，直接在会话要求“在内置预览中打开这个地址”。

## 检查进程、端口和页面

打开当前会话的活动面板，查看 **进程** 区域中的 `onevium-service-demo` 行。它显示名称、运行状态、端口和最近输出；悬停名称可以核对完整命令。

| 检查项  | 本例应看到什么                                                       |
| ---- | ------------------------------------------------------------- |
| 进程   | 服务有实际进程，未立即退出                                                 |
| 就绪   | 检测到 4173 端口，或日志出现 `READY`                                     |
| 页面   | 内置预览显示 `Onevium service demo` 和 `The local preview is ready.` |
| 请求日志 | 打开或刷新页面后出现 `GET /` 等请求行                                       |

进程运行和端口就绪仍不等于页面正确，最后一项页面检查不能省略。需要完整近期日志时，在会话说“读取这个服务最后 50 行日志”，指定刚返回的服务 ID；不要把“最近一行输出”当作完整日志。

## 停止、重启与再次进入

- **停止**：点击目标服务行的方形停止按钮。停止后刷新预览，应无法再从该端口取得新页面；已经显示的旧页面可能仍留在浏览器中。
- **重启**：点击圆形箭头按钮，或在会话要求重启明确的服务 ID。重启沿用原命令和服务记录，再检查新的进程与就绪结果。
- **查看记录**：会话结束并不等于常驻服务自动结束。再次工作前先列出现有服务，避免重复启动。
- **清除已完成项**：活动面板的清理操作移除已结束记录，不用于停止正在运行的服务。

本例结束时停止 `onevium-service-demo`。如需调整端口，应修改示例文件并重新验证；不要结束端口上不属于本项目的进程。

## 处理启动故障

| 现象         | 下一步                                |
| ---------- | ---------------------------------- |
| `node` 找不到 | 回到前置检查，确认当前终端/服务环境能找到 Node.js      |
| 提示端口占用     | 确认占用者；复用本项目已有服务，或选择其他空闲端口，不盲目杀进程   |
| 立即退出       | 读取该服务日志，检查文件名、语法和工作目录              |
| 运行但未就绪     | 检查真实监听端口和 `READY` 输出；运行状态与就绪状态分开判断 |
| 网页内容不对     | 核对地址、端口和服务目录，确认不是另一项目的预览           |
| 重开应用后仍有记录  | 重新检查进程、就绪和页面；恢复记录不等于验收通过           |

## 下一步

用[浏览器自动化](https://onevium.com/zh/docs/browser-automation)检查更多页面行为。修改代码和检查差异见[文件、终端与 Review](https://onevium.com/zh/docs/files-terminal-review)，操作边界见[权限与计划](https://onevium.com/zh/docs/permissions)。