在 Node.js 上部署智能体

最后更新 2026年7月21日查看 Markdown 源文件

使用 Vite 构建和部署 Flue 智能体作为 Node.js 服务器。这是最直接的部署方式，适合大多数场景。

Flue 的 Node 目标是一个长期运行的 HTTP 服务器，而非函数。它在进程中持有智能体会话，并通过长连接提供流式响应。

项目设置

1. 安装依赖

npm install @flue/runtime hono
npm install -D @flue/vite vite

2. 配置 Vite

创建 vite.config.ts：

vite.config.ts

import { flue } from '@flue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [flue()],
  build: {
    ssr: true,
    rollupOptions: {
      input: 'src/app.ts',
    },
  },
});

3. 创建智能体

创建你的第一个智能体：

src/agents/hello.ts

'use agent';
import { useModel } from '@flue/runtime';

export function Hello() {
  useModel('anthropic/claude-sonnet-4-6');
  return '你是一个友好的助手。用简洁的语言回答用户的问题。';
}

4. 创建应用路由

创建 src/app.ts 作为应用的入口点：

src/app.ts

import { createAgentRouter } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { Hello } from './agents/hello.ts';

const app = new Hono();

// 健康检查端点
app.get('/health', (c) => c.text('ok'));

// 挂载智能体路由
app.route('/agents/hello', createAgentRouter(Hello));

export default app;

5. 更新 package.json

package.json

{
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "node dist/server.mjs"
  }
}

构建和运行

开发模式

npm run dev

这将启动一个本地开发服务器，通常在 http://localhost:5173。

生产构建

npm run build
npm run start

构建过程将你的应用编译到 dist/ 目录，生成 dist/server.mjs 作为入口点。

环境变量

必需的环境变量

ANTHROPIC_API_KEY 或 OPENAI_API_KEY：你的模型 provider key
PORT（可选）：服务器监听的端口，默认 3000

设置环境变量

在开发中，创建一个 .env 文件：

ANTHROPIC_API_KEY=sk-...
MODEL_SPECIFIER=anthropic/claude-sonnet-4-6
PORT=8080

在生产中，通过你的部署平台设置环境变量。

持久化

默认情况下，Flue 将对话保存在内存中。要实现持久化，添加一个数据库适配器：

src/db.ts

import { postgres } from '@flue/postgres';
import { Pool } from 'pg';

// 使用 DATABASE_URL 连接字符串创建连接池
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export default postgres({
  query: async (text, params) => (await pool.query(text, params)).rows,
  transaction: async (fn) => {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      const result = await fn(client);
      await client.query('COMMIT');
      return result;
    } catch (e) {
      await client.query('ROLLBACK');
      throw e;
    } finally {
      client.release();
    }
  },
  close: () => pool.end(),
});

Flue 在构建时发现 db.ts 并将其连接到生成的服务器中。参见 Postgres 了解完整的自带驱动运行器。

健康检查

Flue 不会自动生成健康检查端点。在你的 app.ts 中添加一个：

src/app.ts

import { createAgentRouter } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { MyAgent } from './agents/my-agent.ts';

const app = new Hono();

app.get('/health', (c) => c.text('ok'));
app.route('/agents/my-agent', createAgentRouter(MyAgent));

export default app;

流式传输

Flue 使用长连接进行流式传输。确保你的部署平台支持长连接：

反向代理：如果你使用 nginx 或类似工具，配置长超时。
负载均衡器：确保负载均衡器不会过早关闭空闲连接。
客户端：使用 Flue Agent SDK 的 wait() 和 observe() 方法来处理流式传输。

使用 systemd 运行

在 Linux 服务器上，使用 systemd 管理你的 Flue 应用：

/etc/systemd/system/flue.service

[Unit]
Description=Flue Agent Server
After=network.target

[Service]
Type=simple
User=node
WorkingDirectory=/opt/flue-app
ExecStart=/usr/bin/node dist/server.mjs
Environment=PORT=8080
EnvironmentFile=/etc/flue-app.env
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

创建环境文件：

sudo nano /etc/flue-app.env

添加你的环境变量：

ANTHROPIC_API_KEY=sk-...
MODEL_SPECIFIER=anthropic/claude-sonnet-4-6
DATABASE_URL=postgresql://...

启用并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable flue
sudo systemctl start flue
sudo systemctl status flue

查看日志：

sudo journalctl -u flue -f

使用 PM2 运行

PM2 是一个流行的 Node.js 进程管理器：

npm install -g pm2
pm2 start dist/server.mjs --name flue-app
pm2 save
pm2 startup