# Ansible 安装
将 OpenSoul 部署到生产服务器的推荐方式是通过 opensoul-ansible — 一个安全优先架构的自动化安装程序。
# 快速开始
一条命令安装：
bash
curl -fsSL https://raw.githubusercontent.com/opensoul/opensoul-ansible/main/install.sh | bash📦 完整指南：github.com/opensoul/opensoul-ansible
opensoul-ansible 仓库是 Ansible 部署的权威来源。本页是快速概述。
# 你将获得
- 🔒 防火墙优先安全：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
- 🔐 Tailscale VPN：安全远程访问，无需公开暴露服务
- 🐳 Docker：隔离的沙箱容器，仅绑定 localhost
- 🛡️ 纵深防御：4 层安全架构
- 🚀 一条命令设置：几分钟内完成部署
- 🔧 Systemd 集成：带加固的开机自启动
# 要求
- 操作系统：Debian 11+ 或 Ubuntu 20.04+
- 访问权限：Root 或 sudo 权限
- 网络：用于包安装的互联网连接
- Ansible：2.14+（由快速启动脚本自动安装）
# 安装内容
Ansible playbook 安装并配置：
- Tailscale（用于安全远程访问的 mesh VPN）
- UFW 防火墙（仅允许 SSH + Tailscale 端口）
- Docker CE + Compose V2（用于智能体沙箱）
- Node.js 22.x + pnpm（运行时依赖）
- OpenSoul（基于主机，非容器化）
- Systemd 服务（带安全加固的自动启动）
注意：Gateway 网关直接在主机上运行（不在 Docker 中），但智能体沙箱使用 Docker 进行隔离。详情参见沙箱隔离。
# 安装后设置
安装完成后，切换到 opensoul 用户：
bash
sudo -i -u opensoul安装后脚本将引导你完成：
- 新手引导向导：配置 OpenSoul 设置
- 提供商登录：连接 WhatsApp/Telegram/Discord/Signal
- Gateway 网关测试：验证安装
- Tailscale 设置：连接到你的 VPN mesh
# 常用命令
bash
# 检查服务状态
sudo systemctl status opensoul
# 查看实时日志
sudo journalctl -u opensoul -f
# 重启 Gateway 网关
sudo systemctl restart opensoul
# 提供商登录（以 opensoul 用户运行）
sudo -i -u opensoul
opensoul channels login# 安全架构
# 4 层防御
- 防火墙（UFW）：仅公开暴露 SSH（22）+ Tailscale（41641/udp）
- VPN（Tailscale）：Gateway 网关仅通过 VPN mesh 可访问
- Docker 隔离：DOCKER-USER iptables 链防止外部端口暴露
- Systemd 加固：NoNewPrivileges、PrivateTmp、非特权用户
# 验证
测试外部攻击面：
bash
nmap -p- YOUR_SERVER_IP应该显示仅端口 22（SSH）开放。所有其他服务（Gateway 网关、Docker）都被锁定。
# Docker 可用性
Docker 用于智能体沙箱（隔离的工具执行），而不是用于运行 Gateway 网关本身。Gateway 网关仅绑定到 localhost，通过 Tailscale VPN 访问。
沙箱配置参见多智能体沙箱与工具。
# 手动安装
如果你更喜欢手动控制而非自动化：
bash
# 1. 安装先决条件
sudo apt update && sudo apt install -y ansible git
# 2. 克隆仓库
git clone https://github.com/NJX-njx/opensoul-ansible.git
cd opensoul-ansible
# 3. 安装 Ansible collections
ansible-galaxy collection install -r requirements.yml
# 4. 运行 playbook
./run-playbook.sh
# 或直接运行（然后手动执行 /tmp/opensoul-setup.sh）
# ansible-playbook playbook.yml --ask-become-pass# 更新 OpenSoul
Ansible 安装程序设置 OpenSoul 为手动更新。标准更新流程参见更新。
要重新运行 Ansible playbook（例如，用于配置更改）：
bash
cd opensoul-ansible
./run-playbook.sh注意：这是幂等的，可以安全地多次运行。
# 故障排除
# 防火墙阻止了我的连接
如果你被锁定：
- 确保你可以先通过 Tailscale VPN 访问
- SSH 访问（端口 22）始终允许
- Gateway 网关仅通过 Tailscale 访问，这是设计如此
# 服务无法启动
bash
# 检查日志
sudo journalctl -u opensoul -n 100
# 验证权限
sudo ls -la /opt/opensoul
# 测试手动启动
sudo -i -u opensoul
cd ~/opensoul
pnpm start# Docker 沙箱问题
bash
# 验证 Docker 正在运行
sudo systemctl status docker
# 检查沙箱镜像
sudo docker images | grep opensoul-sandbox
# 如果缺失则构建沙箱镜像
cd /opt/opensoul/opensoul
sudo -u opensoul ./scripts/sandbox-setup.sh# 提供商登录失败
确保你以 opensoul 用户运行：
bash
sudo -i -u opensoul
opensoul channels login# 高级配置
详细的安全架构和故障排除：
# 相关内容
- opensoul-ansible — 完整部署指南
- Docker — 容器化 Gateway 网关设置
- 沙箱隔离 — 智能体沙箱配置
- 多智能体沙箱与工具 — 每个智能体的隔离