VPS基础设施
使用Python、FastAPI和n8n为AI代理、工作流自动化和数据工程项目设置个人VPS。
架构概述
此VPS设置提供了一个具有以下服务的开发和生产环境：
核心服务
- AI开发服务器 -用于AI集成和n8n工作流管理的FastMCP+FastAPI服务器
- HostAgent 的 -为特权主机操作（备份、系统任务）提供安全的本地API
- n8n -具有人工智能功能的工作流自动化平台
- n8n工作流 -用于n8n模板搜索的快速HTTP服务器
- Supabase -使用PostgreSQL、Auth、存储和边缘功能完成后端
- 无浏览器 -用于网络自动化的无头Chrome服务
- 数据库 -数据转换和分析
- 集装箱登记处 -自定义镜像的私有Docker注册表
- **** -用于自动化部署的自托管运行器
- 卡迪 -为所有面向公众的服务提供自动SSL/TLS和路由的反向代理
VPS基础设施概述
graph TB
%% Client Layer
Client[Claude Code] -->|MCP/HTTP
Bearer Auth| Caddy[Caddy
Reverse Proxy]
%% Web Layer
Caddy -->|MCP/HTTP| AIDev[MCP Server
Tool Provider]
%% Application Layer
AIDev -->|Create/Read/Update/Delete
N8N API| N8N[N8N
Workflow Automation]
AIDev -->|HTTP| HostAgent[HostAgent
Privileged Operations]
AIDev -->|Search| Workflows[Template Server
2000+ Community Workflows]
%% Host Services
HostAgent -->|Bash/Git| BackupN8N[Backup N8N
Workflows]
HostAgent -->|Search| SearchN8N[N8N Documentation
General Node Descriptions]
HostAgent -->|Search| TypeScriptN8N[N8N Source Code
TypeScript Node Schemas]
%% Automation Layer
GitHub[GitHub Actions] -->|Webhook| Runner[Self-hosted Runner
Docker Deploy]
Runner --> AIDev
Runner --> N8N
Runner --> Supabase[Supabase
PostgreSQL]
Runner --> DBT[DBT
Data Transformation]
Runner --> Browserless[Browserless
Headless Chrome]
%% Security Layer (standalone boxes)
UFW[UFW Firewall
Network Protection]
%% Styling
classDef client fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef web fill:#f3e5f5,stroke:#4a148c,stroke-width: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 Dev Server（容器化）需要与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" # Enable host access# host-agent/.env
HOST=0.0.0.0 # Allow container access
PORT=9000服务发现
服务通过以下方式相互发现：
- 容器名称 作为网络中的主机名
- 本地主机端口 用于外部访问
- 内部网络 用于容器间通信
网络安全
- 防火墙：UFW配置为阻止外部访问服务端口
- 本地主机绑定：服务绑定到
127.0.0.1阻止外部访问 - 容器隔离：服务在隔离的Docker网络中运行
- 认证：所有服务都需要正确的身份验证令牌
快速开始
先决条件
- Docker和Docker Compose
- 已配置UFW防火墙
- DNS指向服务器的域
- SSL证书（通过Caddy）
部署
# Clone repository with submodules
git clone --recurse-submodules /home/david/vps
cd /home/david/vps
# Or if already cloned, initialize submodules
git submodule update --init --recursive
# Configure environment variables
cp host-agent/.env.example host-agent/.env
# Edit .env files with your configuration
# Deploy HostAgent service (primary deployment method)
./deploy.sh
# Deploy individual Docker services
cd docker-compose/[service-name]
docker-compose up -d
# Set up GitHub Actions runner for automated deployments
cd github-runner
./setup-runner.sh
# Configure with GitHub token from repo settings
./start-runner-service.sh
# Verify deployment
docker ps
sudo systemctl status host-agent
sudo systemctl status actions.runner.*服务访问
- API主管: https://supabase.correlion.ai
- Supabase工作室: 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
- 气流: https://airflow.correlion.ai
子模块管理
n8n文档子模块（n8n节点文档）
这 n8n-docs/ 目录通过git子模块包含n8n的全面节点文档。这为MCP工具提供了访问所有n8n节点、凭据和集成的详细文档的权限，同时与官方文档保持同步。
初始设置
# Initialize n8n-docs submodule (first time)
git submodule update --init --recursive n8n-docs
# Or initialize all submodules at once
git submodule update --init --recursive更新n8n文档
# Update n8n documentation to latest version
git submodule update --remote n8n-docs
# Commit the submodule update
git add n8n-docs
git commit -m "Update n8n-docs submodule to latest version"
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节点和集成提供了全面的文档。
故障排除
# If submodule appears empty or outdated
git submodule update --init --remote --force n8n-docs
# Reset submodule to tracked commit
git submodule update --init n8n-docs
# Check submodule status
git submodule status服务管理
启动/停止服务
# Individual Docker services
cd docker-compose/[service-name]
docker-compose up -d
docker-compose down
# HostAgent (systemd service)
sudo systemctl start/stop/restart host-agent
sudo journalctl -u host-agent -f
# GitHub Actions Runner
sudo systemctl start/stop/restart actions.runner.*
sudo journalctl -u actions.runner.* -f
# Deploy script (for HostAgent updates)
./deploy.sh自动化部署
GitHub Actions在推送更改时自动部署服务：
- AI开发服务器：将更改推送到
ai-dev-server/→ 自动构建和部署 - 工作流程:
.github/workflows/deploy-ai-dev-server.yml定义部署 - 跑者：VPS上的自托管运行器执行部署
- 注册表：图片推送到
registry.correlion.ai
容器名称
所有服务都使用干净、可预测的容器名称：
ai-dev-servern8nsupabase-*（多个容器）browserless-chromiumregistrydbtdtc-frontend-app
健康检查
# Service health endpoints
curl http://127.0.0.1:8080/health # AI Dev Server
curl http://127.0.0.1:9000/health # HostAgent
curl http://127.0.0.1:3000/api/platform/profile # Supabase Studio
# Container status
docker ps
docker logs -f [container-name]环境配置
所需的环境变量
每个服务都需要特定的环境变量。关键共享变量：
# Shared authentication
MCP_BEARER_TOKEN=your-secure-token
HOST_AGENT_BEARER_TOKEN=your-secure-token
# n8n Configuration
N8N_BASE_URL=http://n8n:5678
N8N_API_KEY=your-n8n-api-key
# Database (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 workflows backup (via script)
./backup-n8n-workflows.sh
# n8n workflows backup (via HostAgent API)
curl -X POST http://127.0.0.1:9000/backup/n8n \
-H "Authorization: Bearer $HOST_AGENT_BEARER_TOKEN"
# Database backup
docker exec supabase-db pg_dump -U postgres database_name > backup.sql
# Full system state
docker images > docker-images.txt
docker ps -a > docker-containers.txt发展
地方发展
每个服务都有自己的开发设置。请参阅个别服务自述文件：
- AI开发服务器 -FastMCP开发和测试
- HostAgent 的 -当地API开发
- 数据库 -数据转换开发
- -自动部署设置
添加新服务
- 在中创建服务目录
docker-compose/ - 添加
docker-compose.yml通过适当的网络 - 用服务描述更新此README
- 如果需要，添加到部署脚本中
- 如果需要外部访问，请配置Caddy反向代理
- 在中创建GitHub工作流
.github/workflows/用于自动化部署
测试
# Test inter-service communication
docker exec ai-dev-server curl http://host.docker.internal:9000/health
docker exec ai-dev-server curl http://n8n:5678/healthz
# Test external access
curl https://[domain].correlion.ai/health故障排除
常见问题
HostAgent连接被拒绝
- 检查
HOST=0.0.0.0在宿主代理中.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
监控
# Service logs
sudo journalctl -u host-agent -f
docker logs -f ai-dev-server
docker logs -f n8n
# System resources
docker stats
df -h
free -m
# Network connectivity
docker exec [container-name] ping [other-container]
docker exec [container-name] nslookup [service-name]贡献
- 遵循特定服务的开发指南
- 更新README以了解任何网络更改
- 使用适当的脚本测试部署
- 验证所有服务是否正确通信
- 更新环境变量文档
许可证
此项目包含用于VPS基础设施管理的配置和部署脚本。