一、部署目标与系统要求

本指南旨在构建一个完整的IronClaw运行环境，包含以下核心组件：

操作系统：Ubuntu LTS长期支持版本（推荐最新稳定版）
数据库系统：PostgreSQL 16.x（含pgvector向量扩展）
核心服务：IronClaw服务端及配套工具链
交互能力：支持CLI/TUI双模式操作及本地模型推理

系统需满足以下基础条件：

64位架构的物理机/虚拟机
至少4GB内存（生产环境建议8GB+）
50GB可用磁盘空间
网络连接权限（用于依赖安装）

二、环境验证与前置检查

2.1 系统版本确认

执行以下命令验证系统版本：

lsb_release -a

正常输出应包含：

Distributor ID: Ubuntu
Description:    Ubuntu 24.04.4 LTS
Release:        24.04
Codename:       noble

2.2 依赖组件检查

使用包管理器验证关键组件：

# PostgreSQL版本检查
psql --version
# 预期输出：psql (PostgreSQL) 16.x
# pgvector扩展检查
dpkg -l | grep pgvector
# 预期输出：ii postgresql-16-pgvector 0.6.0-1 amd64

2.3 网络连通性测试

确保系统可访问外部软件源：

ping -c 4 archive.ubuntu.com
# 正常响应：64 bytes from xxx.xxx.xxx.xxx: icmp_seq=1 ttl=54 time=20.3 ms

三、核心组件安装流程

3.1 数据库系统部署

执行标准化安装流程：

# 更新软件包索引
sudo apt update
# 安装基础依赖
sudo apt install -y curl ca-certificates gnupg lsb-release
# 添加PostgreSQL官方仓库（如未包含在系统源中）
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
# 安装PostgreSQL及向量扩展
sudo apt install -y postgresql postgresql-contrib postgresql-16-pgvector

3.2 服务启动与验证

# 启用并启动服务
sudo systemctl enable --now postgresql
# 验证服务状态
sudo systemctl status postgresql --no-pager
# 正常状态显示：active (running)

异常处理：若出现active (exited)状态，这是PostgreSQL集群管理服务的正常表现，需通过ps aux | grep postgres确认实际进程。

四、数据库高级配置

4.1 创建专用用户与数据库

# 切换至postgres系统用户
sudo -u postgres psql
# 在PostgreSQL交互终端执行
CREATE USER ironclaw WITH PASSWORD '复杂密码示例@123';
CREATE DATABASE ironclaw OWNER ironclaw;
\c ironclaw
CREATE EXTENSION IF NOT EXISTS vector;
\q

安全建议：

密码应包含大小写字母、数字及特殊字符
生产环境建议使用pg_crypto扩展生成加密密码

4.2 连接测试与故障诊断

使用以下命令验证数据库连接：

PGPASSWORD='复杂密码示例@123' psql -h 127.0.0.1 -U ironclaw -d ironclaw -c "SELECT version();"

常见错误处理：

密码认证失败：
- 检查pg_hba.conf中的认证方法
- 执行ALTER USER ironclaw WITH PASSWORD 'new_password';重置密码
数据库不存在错误：
- 确认数据库名拼写正确
- 使用\l命令查看现有数据库列表
扩展未安装错误：
- 以postgres用户执行CREATE EXTENSION vector;
- 验证/usr/share/postgresql/16/extension/目录下是否存在pgvector相关文件

五、IronClaw服务部署

5.1 安装包获取与验证

从官方渠道获取安装包后，执行完整性检查：

# 示例（实际文件名需替换）
sha256sum ironclaw_v1.2.0_amd64.deb
# 对比官方提供的校验值

5.2 自动化安装流程

sudo dpkg -i ironclaw_v1.2.0_amd64.deb
# 自动解决依赖问题
sudo apt --fix-broken install -y
# 验证安装状态
ironclaw --version
# 预期输出：IronClaw CLI v1.2.0

5.3 初始化配置

执行交互式初始化向导：

sudo ironclaw onboard

按提示完成：

数据库连接配置
存储路径设置
网络参数调整
安全证书生成

六、系统级故障排查

6.1 服务启动失败诊断

日志分析：
```
journalctl -u ironclaw --no-pager -n 50
```
端口冲突检查：
```
sudo netstat -tulnp | grep :5432
```

资源限制验证：

ulimit -a
# 重点检查open files和max user processes参数

6.2 性能优化建议

数据库调优：
- 修改postgresql.conf中的shared_buffers（建议为系统内存的25%）
- 调整work_mem参数（根据查询复杂度设置）
文件系统优化：
- 将数据目录挂载至SSD存储
- 启用noatime挂载选项

内核参数调整：

# 在/etc/sysctl.conf中添加
vm.swappiness=10
kernel.pid_max=65536

七、生产环境部署建议

高可用架构：
- 使用Patroni构建PostgreSQL集群
- 配置流复制与自动故障转移
监控体系搭建：
- 集成Prometheus+Grafana监控套件
- 设置关键指标告警阈值（连接数、查询延迟等）
备份策略：
- 每日逻辑备份（pg_dump）
- 每周物理备份（WAL归档+基础备份）
- 异地容灾备份（对象存储或磁带库）

本指南通过系统化的部署流程设计与故障诊断方法，帮助开发者在Ubuntu LTS环境中快速构建稳定的IronClaw运行环境。实际部署时需根据具体业务场景调整参数配置，并建立完善的运维监控体系确保系统可靠性。

IronClaw 在 Ubuntu LTS 系统中的全流程部署与故障排查指南