虚拟专用服务器

Name: 虚拟专用服务器
Author: alderaan

作者：alderaan3 星标更新：2025-09-05

安装使用来源：spider==github.com

项目介绍

技术文档摘要

VPS 基础设施

用于AI代理、工作流自动化和数据工程项目的个人VPS设置，使用Python、FastAPI和n8n。

架构概述

此VPS设置提供以下服务的开发和生产环境：

核心服务

AI 开发服务器 - 使用FastMCP + FastAPI的AI集成和n8n工作流管理服务器
主机代理 - 用于特权主机操作（备份、系统任务）的安全本地API
n8n - 具有AI能力的工作流自动化平台
n8n 工作流 - 快速HTTP服务器，用于n8n模板搜索
Supabase - 完整后端，包括PostgreSQL、认证、存储和边缘函数
Browserless - 用于网络自动化的无头Chrome服务
DBT - 数据转换和分析
容器仓库 - 私有Docker仓库，用于自定义镜像
GitHub Actions 运行器 - 自托管运行器，用于自动化部署
Caddy - 反向代理，具有自动SSL/TLS和所有面向公众的服务路由

VPS 基础设施概述

graph TB
    %% 客户端层
    Client[Claude Code] -->|MCP/HTTP<br/>Bearer Auth| Caddy[Caddy<br/>反向代理]
    
    %% 网络层
    Caddy -->|MCP/HTTP| AIDev[MCP Server<br/>工具提供者]
    
    %% 应用层
    AIDev -->|创建/读取/更新/删除<br/>N8N API| N8N[N8N<br/>工作流自动化]
    AIDev -->|HTTP| HostAgent[HostAgent<br/>特权操作]
    AIDev -->|搜索| Workflows[模板服务器<br/>2000+ 社区工作流]
    
    %% 主机服务
    HostAgent -->|Bash/Git| BackupN8N[备份 N8N<br/>工作流]
    HostAgent -->|搜索| SearchN8N[N8N 文档<br/>通用节点描述]
    HostAgent -->|搜索| TypeScriptN8N[N8N 源代码<br/>TypeScript 节点模式]
    
    %% 自动化层
    GitHub[GitHub Actions] -->|Webhook| Runner[自托管运行器<br/>Docker 部署]
    Runner --> AIDev
    Runner --> N8N
    Runner --> Supabase[Supabase<br/>PostgreSQL]
    Runner --> DBT[DBT<br/>数据转换]
    Runner --> Browserless[Browserless<br/>无头Chrome]
    
    %% 安全层（独立盒子）
    UFW[UFW 防火墙<br/>网络安全]
    
    %% 样式
    classDef client fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef web fill:#f3e5f5,stroke:#4a148c,stroke-width:2_2px
    classDef app fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef host fill:#f5f5f5,stroke:#424242,stroke-width:2px
    classDef infra fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef container fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    classDef security fill:#ffebee,stroke:#b71c1c,stroke-width:2px
    
    class Client client
    class Caddy web
    class AIDev,HostAgent,Workflows app
    class N8N,Supabase,DBT,Browserless container
    class BackupN8N,SearchN8N,TypeScriptN8N host
    class GitHub,Runner infra
    class UFW security

注：MCP Server指代本仓库中的AI Dev Server服务。

Docker 网络

网络架构

所有服务通过Docker网络连接，并具有特定的网络需求：

Supabase 网络：主要网络（supabase_default），大多数服务加入
主机访问：需要主机访问的服务使用extra_hosts: "host.docker.internal:host-gateway"
端口绑定：服务绑定到127.0.0.1以确保安全性（仅限本地）

关键网络配置

HostAgent ↔ AI 开发服务器通信

AI 开发服务器（容器化）需要与HostAgent（主机服务）进行通信：

AI 开发服务器使用host.docker.internal:9000来访问HostAgent
HostAgent必须绑定到0.0.0.0:9000（而不是127.0.0.1）以接受容器连接
安全：HostAgent的9000端口不对外部暴露（防火墙/端口绑定）

配置：

# docker-compose/ai-dev-server/docker-compose.yml
services:
  ai-dev-server:
    extra_hosts:
      - "host.docker.internal:host-gateway"  # 启用主机访问

# host-agent/.env
HOST=0.0.0.0  # 允许容器访问
PORT=9000

服务发现

服务通过以下方式互相发现：

容器名称作为网络内的主机名
本地主机端口用于外部访问
内部网络用于容器间通信

网络安全

防火墙：UFW配置为阻止对外部服务端口的访问
本地主机绑定：服务绑定到127.0.0.1防止外部访问
容器隔离：服务在隔离的Docker网络中运行
身份验证：所有服务都需要有效的身份验证令牌

快速开始

前提条件

Docker 和 Docker Compose
配置好的UFW防火墙
指向服务器的域名DNS
SSL证书（通过Caddy）

部署

# 克隆包含子模块的仓库
git clone --recurse-submodules <repository-url> /home/david/vps
cd /home/david/vps

# 或者如果已经克隆，初始化子模块
git submodule update --init --recursive

# 配置环境变量
cp host-agent/.env.example host-agent/.env
# 编辑.env文件以您的配置

# 部署HostAgent服务（主要部署方法）
./deploy.sh

# 部署单个Docker服务
cd docker-compose/[service-name]
docker-compose up -d

# 设置GitHub Actions运行器以实现自动化部署
cd github-runner
./setup-runner.sh
# 使用来自仓库设置的GitHub令牌进行配置
./start-runner-service.sh

# 验证部署
docker ps
sudo systemctl status host-agent
sudo systemctl status actions.runner.*

服务访问

Supabase API：https://supabase.correlion.ai
Supabase Studio：http://localhost:3000（需要SSH隧道）
n8n：https://n8n.correlion.ai
AI 开发服务器：https://ai-dev.correlion.ai/llm/mcp/
容器仓库：https://registry.correlion.ai
DTC应用：https://dtc.correlion.ai
Airflow：https://airflow.correlion.ai

子模块管理

n8n-docs 子模块（n8n 节点文档）

n8n-docs/目录包含通过git子模块获取的n8n全面节点文档。这为MCP工具提供了对所有n8n节点、凭证和集成的详细文档访问，同时保持与官方文档同步。

初始设置

# 初始化n8n-docs子模块（首次）
git submodule update --init --recursive n8n-docs

# 或一次性初始化所有子模块
git submodule update --init --recursive

更新n8n文档

# 将n8n文档更新到最新版本
git submodule update --remote n8n-docs

# 提交子模块更新
git add n8n-docs
git commit -m "更新n8n-docs子模块到最新版本"
git push

包含内容

n8n-docs 子模块使用稀疏检出仅包含：

docs/integrations/builtin/app-nodes/* - 应用节点文档
docs/integrations/builtin/core-nodes/* - 核心节点文档
docs/integrations/builtin/cluster-nodes/* - LangChain集群节点文档
docs/integrations/builtin/credentials/* - 凭证文档
docs/integrations/builtin/trigger-nodes/* - 触发节点文档
docs/integrations/builtin/node-types.md & rate-limits.md

这提供了所有n8n节点和集成的全面文档。

故障排除

# 如果子模块看起来为空或过时
git submodule update --init --remote --force n8n-docs

# 将子模块重置为跟踪的提交
git submodule update --init n8n-docs

# 检查子模块状态
git submodule status

服务管理

启动/停止服务

# 单个Docker服务
cd docker-compose/[service-name]
docker-compose up -d
docker-compose down

# HostAgent（systemd服务）
sudo systemctl start/stop/restart host-agent
sudo journalctl -u host-agent -f

# GitHub Actions 运行器
sudo systemctl start/stop/restart actions.runner.*
sudo journalctl -u actions.runner.* -f

# 部署脚本（用于HostAgent更新）
./deploy.sh

自动化部署

当推送更改时，GitHub Actions会自动部署服务：

AI 开发服务器：推送更改到ai-dev-server/ → 自动构建和部署
工作流：.github/workflows/deploy-ai-dev-server.yml定义了部署
运行器：VPS上的自托管运行器执行部署
仓库：镜像推送到registry.correlion.ai

容器名称

所有服务使用干净、可预测的容器名称：

ai-dev-server
n8n
supabase-*（多个容器）
browserless-chromium
registry
dbt
dtc-frontend-app

健康检查

# 服务健康端点
curl http://127.0.0.1:8080/health    # AI 开发服务器
curl http://127.0.0.1:9000/health    # HostAgent
curl http://127.0.0.1:3000/api/platform/profile  # Supabase Studio

# 容器状态
docker ps
docker logs -f [container-name]

环境配置

必要的环境变量

每个服务需要特定的环境变量。关键共享变量：

# 共享认证
MCP_BEARER_TOKEN=your-secure-token
HOST_AGENT_BEARER_TOKEN=your-secure-token

# n8n 配置  
N8N_BASE_URL=http://n8n:5678
N8N_API_KEY=your-n8n-api-key

# 数据库（Supabase）
POSTGRES_PASSWORD=your-db-password
JWT_SECRET=your-jwt-secret
ANON_KEY=your-anon-key
SERVICE_ROLE_KEY=your-service-role-key

安全最佳实践

随机令牌：为所有服务生成安全随机令牌
唯一密码：为每个服务使用不同的密码
环境文件：从不将.env文件提交到版本控制
定期轮换：定期轮换密钥
最小权限：服务以最低必需权限运行

备份和灾难恢复

自动备份

n8n 工作流：通过backup-n8n-workflows.sh脚本或HostAgent API进行自动备份
数据库：Supabase处理自动备份
容器仓库：带有版本控制的镜像存储
配置：所有配置在Git中（除了密钥）

手动备份命令

# n8n 工作流备份（通过脚本）
./backup-n8n-workflows.sh

# n8n 工作流备份（通过HostAgent API）
curl -X POST http://127.0.0.1:9000/backup/n8n \
  -H "Authorization: Bearer $HOST_AGENT_BEARER_TOKEN"

# 数据库备份
docker exec supabase-db pg_dump -U postgres database_name > backup.sql

# 完整系统状态
docker images > docker-images.txt
docker ps -a > docker-containers.txt

开发

本地开发

每个服务都有自己的开发设置。参见各个服务的README：

AI 开发服务器 - FastMCP开发和测试
HostAgent - 本地API开发
DBT - 数据转换开发
GitHub 运行器 - 自动化部署设置

添加新服务

在docker-compose/中创建服务目录
添加具有适当网络配置的docker-compose.yml
更新此README以包含服务描述
如需添加到部署脚本中
如果需要外部访问，请配置Caddy反向代理
在.github/workflows/中创建GitHub工作流以实现自动化部署

测试

# 测试服务间通信
docker exec ai-dev-server curl http://host.docker.internal:9000/health
docker exec ai-dev-server curl http://n8n:5678/healthz

# 测试外部访问
curl https://[domain].correlion.ai/health

故障排除

常见问题

HostAgent连接被拒绝

检查HOST=0.0.0.0在host-agent .env中
验证HostAgent服务是否正在运行：sudo systemctl status host-agent
测试连通性：docker exec ai-dev-server curl http://host.docker.internal:9000/health

容器网络问题

验证容器是否在正确的网络上：docker network ls
检查容器名称是否匹配docker-compose配置
确保已配置extra_hosts以访问主机

服务发现失败

使用容器名称作为主机名
检查docker-compose文件中的网络配置
验证服务是否正在运行：docker ps

监控

# 服务日志
sudo journalctl -u host-agent -f
docker logs -f ai-dev-server
docker logs -f n8n

# 系统资源
docker stats
df -h
free -m

# 网络连通性
docker exec [container-name] ping [其他容器]
docker exec [container-name] nslookup [服务名称]

贡献

遵循服务特定的开发指南
更新README以反映任何网络变更
使用适当的脚本测试部署
验证所有服务是否正确通信
更新环境变量文档

许可

该项目包含用于VPS基础设施管理的配置和部署脚本。