服务器集群运维文档一、集群概览1. 集群信息A. 节点列表主机名IP 地址角色操作系统内核版本xlab-ecs-node2192.168.86.152Kubernetes 节点Ubuntu 22.04.5 LTS5.15.0-173-genericxlab-ecs-node3192.168.86.153Docker 容器节点Ubuntu 22.04.5 LTS5.15.0-173-genericB. 集群用途xlab-ecs-node2：Kubernetes 集群工作节点xlab-ecs-node3：Docker 容器部署节点二、硬件配置1. CPU 配置A. 处理器规格型号：Intel Xeon E5-2697 v2 @ 2.70GHz核心数：24 核（12 核/单线程 × 2 线程）频率范围：1200 MHz - 3500 MHz架构：x86_64B. 虚拟化支持VT-x：已启用VT-d：已启用2. 内存配置节点总内存可用内存Swapxlab-ecs-node262 GB约 58 GB8 GBxlab-ecs-node347 GB约 40 GB8 GB3. 存储配置A. 磁盘列表节点设备容量类型挂载点用途xlab-ecs-node2sda931.8 GBSSD/系统盘xlab-ecs-node3sda931.8 GBSSD/系统盘xlab-ecs-node3sdb238.5 GB未挂载-预留扩展B. 文件系统类型：ext4主分区：/dev/sda2 挂载于 /4. 网络配置A. 网卡信息网卡 1：enp11s0（Broadcom BCM57762 千兆以太网）网卡 2：enp12s0（Broadcom BCM57762 千兆以太网）无线网卡：wlp13s0（Broadcom BCM4360 802.11ac）B. 网络绑定绑定模式：bond0（Active-Backup）状态：双网卡绑定，高可用C. 网络接口对比节点bond0 MAC 地址容器网络xlab-ecs-node296:fd:b9:44:54:6bflannel.1 + cni0xlab-ecs-node3d2:4f:29:66:e9:dfdocker0 + 多个 bridge5. 显卡配置A. GPU 规格型号：AMD Radeon R7 370 / R9 270X/370X（双卡）芯片：Curacao XT / Trinidad XT数量：每台服务器 2 张三、系统环境1. 操作系统A. 基本信息发行版：Ubuntu 22.04.5 LTS（Jammy Jellyfish）版本 ID：22.04架构：x86_642. 内核配置A. 当前内核版本：5.15.0-173-generic编译时间：2026 年 3 月 6 日B. 启动参数BOOT_IMAGE=/boot/vmlinuz-5.15.0-173-generic root=UUID=<分区-UUID> ro intel_idle.max_cstate=1 mce=offC. 参数说明参数值作用intel_idle.max_cstate1限制 CPU C-State 到 C1，降低延迟mceoff禁用 Machine Check ExceptionD. GRUB 配置默认启动项：0等待时间：5 秒内核参数：intel_idle.max_cstate=1 mce=off3. 时区配置节点时区UTC 偏移xlab-ecs-node2Asia/ShanghaiUTC+8xlab-ecs-node3Etc/UTCUTC+0注意：两台节点时区不一致，建议统一为 Asia/Shanghai。4. 已安装内核当前版本：5.15.0-173-generic旧版本：5.15.0-119-generic（备用）四、容器运行时1. 运行时对比节点容器运行时网络插件xlab-ecs-node2Containerd + KubernetesFlannel + CNIxlab-ecs-node3DockerBridge 模式2. Kubernetes 节点（node2）A. 网络组件flannel.1：Overlay 网络cni0：CNI 网桥veth*：容器虚拟网卡B. Pod 网络MTU：1450网段：由 Flannel 自动分配3. Docker 节点（node3）A. 网络组件docker0：Docker 默认网桥br-*：用户自定义网桥veth*：容器虚拟网卡B. 容器网络MTU：1500模式：Bridge五、监控指标1. 系统资源A. CPU 监控使用率阈值：> 80% 告警负载阈值：1 分钟 > 核心数 × 0.8B. 内存监控使用率阈值：> 85% 告警Swap 使用：> 1 GB 告警C. 磁盘监控使用率阈值：> 80% 告警inode 使用率：> 80% 告警2. 网络监控A. 流量监控入站流量：峰值 > 500 Mbps 告警出站流量：峰值 > 500 Mbps 告警B. 连接监控TCP 连接数：> 10000 告警连接错误率：> 1% 告警3. 容器监控A. Kubernetes 节点Pod 数量：当前运行约 6 个 Pod容器状态：Running/Failed 比例B. Docker 节点容器数量：当前运行约 20+ 容器容器状态：Up/Exited 统计4. 硬件监控A. 温度监控CPU 温度：> 80°C 告警硬盘温度：> 50°C 告警B. 磁盘健康SMART 状态：定期检查坏块检测：每月执行六、维护操作1. 日常巡检A. 每日检查项系统负载：uptime磁盘空间：df -h内存使用：free -h服务状态：systemctl status容器状态：kubectl pods / docker psB. 每周检查项日志审查：journalctl安全更新：apt list --upgradable备份验证：检查备份完整性2. 内核升级A. 升级流程# 1. 更新软件包索引 apt update # 2. 查看可用内核版本 apt list linux-image-generic # 3. 安装新内核 apt install linux-image-generic # 4. 更新 GRUB update-grub # 5. 重启系统 rebootB. 回滚流程# 1. 重启时选择旧内核 # 2. 或在 GRUB 菜单中选择Advanced options # 3. 选择 5.15.0-119-generic 内核启动 # 永久切换为旧内核 vim /etc/default/grub # 修改 GRUB_DEFAULT=0 为 GRUB_DEFAULT="1>2" update-grub3. 时区统一A. 修改 node3 时区# 统一为上海时区 timedatectl set-timezone Asia/Shanghai # 验证 timedatectl4. 磁盘扩容（node3）A. 挂载 sdb 磁盘# 1. 查看磁盘信息 lsblk fdisk -l /dev/sdb # 2. 创建分区 fdisk /dev/sdb # n -> p -> 1 -> w # 3. 格式化 mkfs.ext4 /dev/sdb1 # 4. 创建挂载点 mkdir -p /data # 5. 挂载 mount /dev/sdb1 /data # 6. 永久挂载 echo '/dev/sdb1 /data ext4 defaults 0 2' >> /etc/fstab5. 网络故障排查A. 网卡状态检查# 查看网卡状态 ip link show # 查看 bond 状态 cat /proc/net/bonding/bond0 # 查看网络统计 ip -s link showB. 网络连通性测试# Ping 测试 ping -c 4 192.168.86.1 # 端口测试 telnet <目标IP> <端口> # 路由跟踪 traceroute <目标IP>七、应急预案1. 系统无法启动A. GRUB 修复# 1. 使用 Live CD 启动 # 2. 挂载根分区 mount /dev/sda2 /mnt # 3. 重新安装 GRUB grub-install --root-directory=/mnt /dev/sda # 4. 重启B. 内核参数恢复# 编辑 GRUB 配置 vim /etc/default/grub # 重置为默认 GRUB_CMDLINE_LINUX_DEFAULT="" # 更新 GRUB update-grub2. 磁盘满载A. 快速清理# 清理 APT 缓存 apt clean apt autoclean # 清理日志 journalctl --vacuum-size=1G # 清理 Docker docker system prune -aB. 大文件查找# 查找大于 1G 的文件 find / -size +1G -exec ls -lh {} \; # 查看目录占用 du -sh /* | sort -hr3. 内存溢出A. 查看内存使用# 查看进程内存占用 ps aux --sort=-%mem | head -20 # 查看容器内存占用 docker statsB. 释放内存# 清理页面缓存 sync echo 3 > /proc/sys/vm/drop_caches # 重启占用内存高的服务 systemctl restart <服务名>八、安全加固1. 系统加固A. SSH 配置禁用 root 远程登录（可选）配置密钥认证修改默认端口B. 防火墙配置# 安装 ufw apt install ufw # 允许必要端口 ufw allow 22/tcp ufw allow 80/tcp ufw allow 443/tcp # 启用防火墙 ufw enable2. 容器安全A. 限制容器资源CPU 限制内存限制磁盘 IO 限制B. 网络隔离使用网络策略限制容器间通信九、备份策略1. 系统备份A. 配置文件备份/etc 目录/home 目录应用配置B. 备份周期增量备份：每日全量备份：每周异地备份：每月2. 数据备份A. 数据库备份MySQL：mysqldump 每日Redis：RDB + AOFB. 容器数据备份Volume 数据定期备份配置文件版本控制参考资料Ubuntu 22.04 LTS 官方文档Kubernetes 官方文档Docker 官方文档
Zookeeper 容器连接超时故障复盘一、事件概述1. 事件背景生产环境 Zookeeper 容器每天需要手动重启一次，否则会出现端口通但无法连接的问题。容器已运行 20 个月，问题近期频繁出现。2. 影响范围A. 影响用户数依赖 Zookeeper 的所有业务系统B. 影响时长问题累积约 24 小时后必须重启C. 影响功能服务注册发现、分布式协调、配置管理3. 严重程度P2 级故障（影响业务可用性，需每日人工干预）二、事件时间线1. 问题发现A. 现象描述端口 2181 可以 telnet 通客户端连接超时或失败重启容器后恢复正常B. 问题特征容器运行时间越长，问题越严重每天需要手动重启一次服务器：192.168.124.48（已脱敏）容器：confluentinc/cp-zookeeper:7.3.22. 问题诊断A. 日志分析通过日志分析发现配置问题：tickTime=3000 minSessionTimeout=6000 maxSessionTimeout=60000 (只有 60 秒) clientPortListenBacklog=-1B. 根因定位maxSessionTimeout 只有 60 秒，长连接客户端被断开clientPortListenBacklog 使用系统默认值，高负载时连接队列问题无自动重启策略，异常时无法自动恢复3. 解决方案实施sequenceDiagram participant O as 运维人员 participant S as 服务器 participant Z as Zookeeper O->>S: 创建配置文件 O->>Z: 停止旧容器 Note over Z: 容器卡住需强制删除 O->>S: kill 僵死进程 O->>Z: 强制删除容器 O->>Z: 创建新容器 Z-->>O: 启动成功 O->>Z: 验证配置三、问题分析1. 直接原因A. Session Timeout 配置过小maxSessionTimeout 只有 60 秒（20 × tickTime），对于需要长连接的客户端来说太短。B. 连接队列配置不当clientPortListenBacklog=-1，使用系统默认值，在高负载或连接累积情况下可能导致连接队列问题。C. 无自动重启机制RestartPolicy=no，容器异常时不会自动重启。2. 根本原因（5 Whys 分析）A. 为什么出现连接问题？Session 超时时间过短，客户端长连接被服务端主动断开。B. 为什么超时时间过短？使用默认配置，未根据业务场景调整参数。C. 为什么没有自动恢复？容器未配置自动重启策略。D. 为什么配置不当？缺乏容器化中间件的配置规范和最佳实践。3. 配置影响分析graph TB A[配置不当] --> B[maxSessionTimeout=60s] A --> C[clientPortListenBacklog=-1] A --> D[RestartPolicy=no] B --> E[长连接断开] C --> F[连接队列溢出] D --> G[异常无法自愈] E --> H[客户端连接失败] F --> H G --> I[需人工重启] H --> J[业务受影响] I --> J四、解决方案1. 临时方案A. 实施措施每天手动重启容器B. 效果评估临时恢复服务需持续人工干预治标不治本2. 永久方案A. 配置优化创建自定义配置文件 zookeeper.properties：tickTime=2000 dataDir=/var/lib/zookeeper/data dataLogDir=/var/lib/zookeeper/log clientPort=2181 initLimit=10 syncLimit=5 maxSessionTimeout=300000 minSessionTimeout=4000 clientPortListenBacklog=1024 server.1=zookeeper:2888:3888B. 容器重新创建docker run -d \ --name zookeeper \ --restart=unless-stopped \ --network root_yewu-network \ -p 2181:2181 \ -p 1812:2181 \ -v /root/data/zookeeper/data:/var/lib/zookeeper/data \ -v /root/data/zookeeper/log:/var/lib/zookeeper/log \ -v /root/data/zookeeper/secrets:/etc/zookeeper/secrets \ -v /root/data/zookeeper/zookeeper.properties:/etc/kafka/zookeeper.properties \ -e ZOOKEEPER_CLIENT_PORT=2181 \ -e ZOOKEEPER_SERVER_ID=1 \ -e ZOOKEEPER_SERVERS=zookeeper:2888:3888 \ harbor.op123.ren:44301/confluentinc/cp-zookeeper:7.3.2C. 关键参数变更参数修复前修复后说明tickTime3000ms2000ms基准时间单位maxSessionTimeout60秒300秒5分钟，足够长连接使用minSessionTimeout6秒4秒最小会话超时clientPortListenBacklog-11024连接队列大小RestartPolicynounless-stopped自动重启3. 预防措施A. 建立配置规范为常用中间件制定标准配置模板B. 健康检查机制配置容器健康检查和监控告警C. 定期巡检定期检查容器运行状态和配置参数五、经验总结1. 做得好的地方通过日志分析准确定位根因使用配置文件挂载方式，便于后续维护配置自动重启策略，提高可用性2. 需要改进的地方缺少容器化中间件的配置规范缺少监控告警机制问题存在时间较长才处理3. 流程优化建议A. 中间件部署规范制定统一的中间件容器化部署规范，包括：必须配置自动重启策略关键参数需要根据业务场景调整配置文件外部化管理B. 监控告警体系添加 Zookeeper 连接数监控添加容器健康状态监控配置异常自动告警C. 定期巡检机制每周检查容器运行状态每月检查配置参数合理性定期更新镜像版本六、配置参考1. Zookeeper 核心参数说明参数默认值推荐值说明tickTime20002000ZK 时间单位（毫秒）initLimit1010初始连接同步超时（tickTime 数）syncLimit55同步请求超时（tickTime 数）maxSessionTimeout60000300000最大会话超时（毫秒）minSessionTimeout60004000最小会话超时（毫秒）clientPortListenBacklog-11024连接队列大小2. 容器启动最佳实践必须配置 --restart 策略数据目录必须持久化挂载配置文件外部化管理配置健康检查机制添加资源限制（memory、CPU）参考资料Apache Zookeeper 官方文档Confluent Platform Zookeeper 配置
Project N.O.M.A.D. 离线生存计算机系统一、概述1. 项目简介A. 是什么Project N.O.M.A.D.（Node for Offline Media, Archives, and Data）是一个自包含的离线优先知识和教育服务器。它通过 Docker 容器化技术整合了关键工具、知识库和本地 AI，能够在任何时间、任何地点保持信息获取和赋能能力。B. 为什么需要网络基础设施可能因自然灾害、战争或其他突发事件而中断某些环境下互联网访问受限或不可用需要保证数据隐私和完全的本地控制教育资源在偏远地区的可用性问题C. 能做什么离线访问完整的维基百科、医学参考资料和电子书本地 AI 聊天助手，支持文档上传和语义搜索Khan Academy 课程学习平台，支持进度跟踪离线地图下载和导航数据加密、编码和分析工具本地笔记系统2. 核心特性A. 完全离线运行系统仅在初始安装时需要网络连接，之后可完全脱机运行，无内置遥测功能。B. 容器化架构基于 Docker 的容器编排，所有工具和服务以容器形式运行，便于管理和更新。C. 统一管理界面提供 Web 界面（Command Center）统一管理所有服务和资源。D. 本地 AI 能力通过 Ollama 和 Qdrant 实现本地大语言模型和向量数据库，支持 RAG（检索增强生成）。3. 项目背景A. 开发团队由 Crosstalk Solutions 开发和维护，采用 Apache 2.0 开源许可证。B. 社区支持拥有活跃的 Discord 社区和社区排行榜，用户可以分享硬件配置和性能数据。二、系统架构1. 整体架构Project N.O.M.A.D. 采用分层架构设计，通过 Docker 容器化技术整合多个独立服务。graph TB subgraph 用户层 Browser[Web 浏览器] end subgraph 管理层 CC[Command Center 管理界面] API[REST API] end subgraph 服务层 Kiwix[Kiwix 离线知识库] Kolibri[Kolibri 教育平台] Ollama[Ollama AI 服务] Qdrant[Qdrant 向量数据库] CyberChef[CyberChef 数据工具] FlatNotes[FlatNotes 笔记服务] Maps[ProtoMaps 离线地图] end subgraph 数据层 MySQL[(MySQL 数据库)] ZIM[ZIM 文件存储] Content[用户内容存储] end subgraph 基础设施层 Docker[Docker 容器引擎] Linux[Linux 操作系统] end Browser --> CC CC --> API API --> Kiwix API --> Kolibri API --> Ollama API --> Qdrant API --> CyberChef API --> FlatNotes API --> Maps Ollama --> Qdrant CC --> MySQL Kiwix --> ZIM FlatNotes --> Content API --> Docker Kiwix --> Docker Kolibri --> Docker Docker --> Linux2. 组件说明A. Command Center核心管理界面，提供统一的服务管理、配置和用户交互入口。B. 服务层组件Kiwix：离线知识库服务，支持 ZIM 格式内容Kolibri：离线教育平台，支持课程管理和进度跟踪Ollama：本地大语言模型运行时Qdrant：向量数据库，用于语义搜索和 RAGCyberChef：多功能数据处理工具FlatNotes：Markdown 笔记应用ProtoMaps：离线地图瓦片服务C. 数据存储MySQL：存储元数据、配置和用户数据ZIM 文件：存储离线知识库内容本地文件系统：用户上传内容和笔记3. 交互流程A. AI 对话流程sequenceDiagram participant U as 用户 participant CC as Command Center participant O as Ollama participant Q as Qdrant participant KB as 知识库 U->>CC: 发送问题 CC->>Q: 向量搜索 Q-->>CC: 返回相关文档 CC->>O: 构建提示词 O-->>CC: 返回响应 CC-->>U: 显示答案 Note over U,KB: 用户可上传文档 U->>CC: 上传文档 CC->>KB: 存储文档 CC->>Q: 建立向量索引B. 内容获取流程初始安装时从互联网下载所有依赖和容器镜像，之后完全离线运行。三、功能模块1. 离线知识库A. Kiwix 集成通过 Kiwix 提供 ZIM 格式的离线内容访问，包括：完整维基百科（无图片、有图片、全版本）医学参考资料（如维基医学）生存指南和急救手册电子书和文档库B. 内容管理Command Center 提供：ZIM 文件选择器内容库管理内容浏览器2. AI 助手A. 本地 LLM通过 Ollama 运行本地大语言模型，支持多种开源模型：小型模型（1-3B）：适合基础硬件中型模型（3-8B）：需要较好的 CPU/iGPU大型模型（7B+）：需要专用 GPUB. RAG 功能文档上传和解析Qdrant 向量搜索语义检索增强生成C. 性能基准根据社区硬件排行榜数据：集成显卡：5-55 tokens/secRTX 3060：约 100-800 tokens/secRTX 3090：可运行 13B+ 参数模型3. 教育平台A. Kolibri 集成提供 Khan Academy 课程，支持：多学科视频课程练习题和测验进度跟踪多用户支持B. 离线地图基于 ProtoMaps 提供：区域地图下载搜索和导航功能离线地图瓦片服务4. 工具集A. CyberChef多功能数据处理工具，支持：加密和解密编码转换数据格式转换哈希计算数据分析B. FlatNotes本地笔记应用，支持：Markdown 编辑笔记分类搜索功能C. 系统基准测试内置硬件评分工具：NOMAD 评分系统社区排行榜对比性能优化建议四、安装部署1. 系统要求A. 最低配置处理器：2 GHz 双核或更好内存：4 GB RAM存储：至少 5 GB 可用空间操作系统：基于 Debian 的 Linux（推荐 Ubuntu）网络：安装时需要稳定的互联网连接B. 推荐配置（AI 功能）处理器：AMD Ryzen 7 或 Intel Core i7 或更好内存：32 GB RAM显卡：NVIDIA RTX 3060 或 AMD 同等级别或更好存储：至少 250 GB SSD操作系统：Ubuntu 22.04+ 或 Debian 12+2. 快速安装A. 一键安装脚本适用于基于 Debian 的操作系统：sudo apt-get update && sudo apt-get install -y curl && \ curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh -o install_nomad.sh && \ sudo bash install_nomad.shB. 访问服务安装完成后，在浏览器中访问：本地：http://localhost:8080远程：http://设备IP:8080C. 首次配置运行设置向导：选择要安装的内容集合配置 AI 模型下载初始内容3. 高级安装A. Docker Compose 方式适合需要自定义配置的高级用户：# 下载模板文件 curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/management_compose.yaml -o docker-compose.yml # 编辑配置文件 nano docker-compose.yml # 启动服务 docker compose up -dB. 自定义选项端口配置存储路径环境变量资源限制4. 管理脚本安装完成后，以下脚本位于 /opt/project-nomad 目录：# 启动所有容器 sudo bash /opt/project-nomad/start_nomad.sh # 停止所有容器 sudo bash /opt/project-nomad/stop_nomad.sh # 更新 Command Center sudo bash /opt/project-nomad/update_nomad.sh5. 卸载curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/uninstall_nomad.sh -o uninstall_nomad.sh && \ sudo bash uninstall_nomad.sh五、硬件配置指南1. 预算配置（$150-$300）A. 硬件规格设备：翻新迷你 PC 或小型台式机处理器：Intel Core i5/i7（8代+）或 AMD Ryzen 5内存：16-32 GB DDR4 RAM存储：500 GB SSD显卡：集成显卡B. 性能预期NOMAD 评分：15-40完整的维基百科、地图和教育平台基础 AI 聊天（1-3B 参数模型）生成速度：5-20 tokens/secC. 适用场景离线知识库访问、基础 AI 对话、教育学习2. 推荐配置（$500-$800）A. 硬件规格设备：Minisforum、Beelink 或类似紧凑型迷你 PC处理器：AMD Ryzen 7/9（8700G/8845HS/7840HS）内存：32 GB DDR5 RAM存储：1 TB NVMe SSD显卡：集成 AMD Radeon 780M/890MB. 性能预期NOMAD 评分：80-95AI 生成速度：30-55 tokens/sec支持 3-8B 参数模型流畅的对话体验C. 适用场景完整的 Project N.O.M.A.D. 体验，社区最流行的配置3. 高性能配置（$1000+）A. 硬件规格设备：桌面 PC 或带 eGPU 的迷你 PC处理器：AMD Ryzen 7/9 或 Intel Core i7/i9内存：32-64 GB RAM存储：1-2 TB NVMe SSD显卡：NVIDIA RTX 3060 12GB 或更好B. 性能预期NOMAD 评分：85-100RTX 3060：100+ tokens/secRTX 3090：可运行 13B+ 参数模型支持 7B 模型极速响应C. 适用场景重度 AI 工作负载、大型模型运行、专业用途4. 离网供电A. 太阳能供电迷你 PC 功耗：15-65W推荐配置：太阳能板 + 电池 + UPSB. 网络共享连接 WiFi 路由器或接入点允许多设备同时访问六、使用指南1. Command Center 界面A. 主要功能服务状态监控内容库管理AI 聊天界面设置向导B. 内容管理浏览已安装的 ZIM 文件下载新的内容包管理教育课程2. AI 聊天使用A. 开始对话在 AI Chat 模块中：选择已安装的模型输入问题或提示词查看响应结果B. 上传文档支持多种文档格式自动建立向量索引基于文档内容的问答3. 系统基准测试A. 运行测试在 Command Center 中运行 System Benchmark：测试 CPU 性能测试 GPU 性能（如有）生成 NOMAD 评分B. 社区对比访问排行榜网站查看相似配置的性能获取优化建议七、安全与隐私1. 隐私保护A. 零遥测设计Project N.O.M.A.D. 不包含任何遥测功能，完全本地运行。B. 网络检测系统通过访问 Cloudflare 的 1.1.1.1 端点检测网络连接状态，仅用于判断是否在线。2. 安全考虑A. 无认证机制默认情况下不包含身份认证，任何人都可以访问所有服务。B. 网络隔离推荐的安全实践：使用网络级访问控制通过防火墙管理端口暴露不建议直接暴露到公网C. 多用户场景未来版本可能添加可选的认证层，支持：家长控制教师和管理员账户不同权限级别3. 端口管理通过防火墙规则控制哪些服务暴露给网络：Web 界面：默认 8080其他服务端口可根据需要开放或关闭八、社区与资源1. 官方资源项目网站：https://www.projectnomad.us/GitHub 仓库：https://github.com/Crosstalk-Solutions/project-nomadDiscord 社区：https://discord.com/invite/crosstalksolutions硬件指南：https://www.projectnomad.us/hardware排行榜：https://benchmark.projectnomad.us/2. 贡献指南项目欢迎社区贡献，流程如下：先创建 Issue 讨论变更Fork 仓库并创建分支遵循代码规范提交 Pull Request使用 Conventional Commits 格式3. 版本管理项目使用语义化版本，版本号定义在根目录的 package.json 中。发布说明存储在 admin/docs/release-notes.md。参考资料Project N.O.M.A.D. GitHub RepositoryProject N.O.M.A.D. Official WebsiteHardware GuideCommunity Leaderboard
Folio-OCR 三栏文档 OCR 工作台一、概述1. 简介A. 是什么Folio-OCR 是一款基于 GLM-OCR 和 Ollama 的三栏文档 OCR 工作台，专为书籍和文档的日常批量识别设计。它提供了一个现代化的 Web 界面，支持图片和 PDF 文件的批量光学字符识别，并具备智能版面分析、实时编辑和多种格式导出功能。B. 为什么学解决文档数字化过程中的人工识别效率问题利用本地化 OCR 方案保护数据隐私学习 FastAPI 前后端分离架构和版面分析技术了解如何将大型语言模型集成到实际应用中C. 学完能做什么搭建本地化的 OCR 识别服务批量处理 PDF 和图片文档使用版面分析技术提高识别准确率将识别结果导出为 Markdown、TXT 或 Word 文档2. 前置知识A. 必备技能基础的 Linux 命令行操作了解 Docker 基础概念B. 推荐知识Python 基础编程知识Web 开发基础概念OCR 和版面分析基础二、环境准备1. 系统要求操作系统：Linux、macOS、Windows 10/11Docker：20.10+（推荐使用 Docker 部署）Python：3.10+（本地部署）Ollama：已安装（本地部署）硬件：建议 8GB+ 内存，有 NVIDIA 显卡可获得更好性能2. 安装步骤Docker 部署（推荐）# 1. 克隆项目 git clone https://github.com/vorojar/Folio-OCR.git cd Folio-OCR # 2. 启动服务 docker compose up -d # 3. 下载 OCR 模型（约 2GB，只需执行一次） docker compose exec ollama ollama pull glm-ocr本地部署# 安装依赖 pip install -r requirements.txt # 拉取模型 ollama pull glm-ocr # 启动服务 python server.py # Windows 一键启动 start.bat3. 验证安装打开浏览器访问 http://localhost:3000，若能看到界面则表示安装成功。# 检查 Ollama 状态 curl http://localhost:11434/api/tags # 检查服务状态 curl http://localhost:3000/api/status三、核心概念1. 基本术语GLM-OCR：智谱 AI 开发的 OCR 模型，用于图像文字识别Ollama：本地化大模型运行平台，提供 GLM-OCR 的推理服务FastAPI：Python Web 框架，用于构建后端 APIPP-DocLayoutV3：PaddlePaddle 的文档版面分析模型SQLite：轻量级数据库，用于持久化存储文档和 OCR 结果版面分析：自动检测文档中的标题、正文、表格、图片等区域2. 工作原理graph LR User[用户] --> FE[前端界面] FE --> API[FastAPI 后端] API --> DB[(SQLite 数据库)] API --> Layout[版面分析模型] API --> Ollama[Ollama OCR 服务] Layout --> API Ollama --> API API --> FE API --> Storage[文件存储]系统采用三层架构设计：前端层：提供三栏式用户界面，负责文件上传、结果显示和用户交互后端层：FastAPI 提供 RESTful API，处理版面分析、OCR 调用和数据持久化服务层：Ollama 提供 OCR 推理服务，PP-DocLayoutV3 提供版面分析能力四、快速上手1. 基本使用流程graph TD A[启动服务] --> B[上传文档] B --> C[自动拆页处理] C --> D[版面分析] D --> E[OCR 识别] E --> F[编辑校对] F --> G[导出文档]2. 上传文档支持以下文件格式：图片：PNG、JPG、GIF、BMP文档：PDF支持多文件混合上传，系统会自动将所有文件合并为一个文档，并按页码顺序排列。3. OCR 识别系统提供两种 OCR 模式：单页识别：对选中的页面进行 OCR批量识别：点击 OCR All Pages 一键处理全部页面识别过程中会显示实时进度条和 ETA 时间估算，用户可以随时点击 Stop 按钮中断处理。4. 编辑与导出识别结果支持：Edit 模式：纯文本编辑，便于手动修正Preview 模式：实时渲染 HTML 表格和 Markdown 格式段落重排：自动合并因换行断开的段落导出格式：Markdown（.md）纯文本（.txt）Word 文档（.docx）五、核心功能1. OCR 引擎A. 版面分析使用 PP-DocLayoutV3 模型进行智能版面分析，自动识别以下区域：标题（title）正文（text）表格（table）图片（figure）页眉页脚、脚注、页码（自动跳过）B. 智能合并相邻文本区域会自动合并，减少 OCR 调用次数。例如 11 个文本区域可合并为 3 组，实现约 2.5 倍加速。C. LaTeX 处理自动将模型输出的 LaTeX 符号转换为 Unicode 字符：$\textcircled{1}$ → ①$\frac{1}{2}$ → ½其他常见数学符号D. 清理处理自动清理模型输出的 Markdown 围栏标记。2. 数据持久化使用 SQLite 数据库存储以下信息：文档元数据（ID、文件名、创建时间）页面信息（页码、文件名、OCR 结果、版面区域、处理时间）自动保存编辑内容（800ms 防抖）3. 界面交互A. 三栏布局左栏：页面缩略图，支持快速切换页面中栏：图片预览，显示版面分析区域框右栏：OCR 结果，支持编辑和预览B. 双向高亮点击图片中的区域框会高亮对应的文本块，点击文本块会高亮对应的图片区域。C. 全文搜索支持 Ctrl+F 全文搜索，跨页高亮显示匹配内容并统计命中次数。D. 键盘导航使用 ↑↓ 方向键快速切换页面。4. 网络容错所有网络请求都带有超时保护：状态检查：5 秒OCR 调用：180 秒其他请求：30 秒Ollama 断开后 UI 不会冻结，超时后会自动恢复可操作状态并通过 Toast 弹窗通知用户。六、技术架构1. 后端架构graph TB subgraph 后端服务 API[FastAPI Server] DB[(SQLite)] Layout[PP-DocLayoutV3] Uploads[uploads/ 目录] end subgraph 外部服务 Ollama[Ollama GLM-OCR] end API --> DB API --> Layout API --> Uploads API --> Ollama2. 版面分析流程sequenceDiagram participant U as 用户 participant API as FastAPI participant L as Layout 模型 participant O as Ollama U->>API: 上传图片 API->>L: 版面分析 L-->>API: 返回区域列表 API->>API: 合并相邻区域 loop 对每个合并区域 API->>O: OCR 调用 O-->>API: 返回识别文本 end API->>U: 返回完整结果3. 数据库设计erDiagram documents ||--o{ pages : 包含 documents { string doc_id PK string filename string created_at } pages { string doc_id FK integer num string filename text ocr_text text ocr_regions real ocr_time }4. 主要依赖依赖版本用途fastapi>=0.100.0Web 框架uvicorn>=0.23.0ASGI 服务器httpx>=0.25.0异步 HTTP 客户端pymupdf>=1.23.0PDF 处理Pillow>=10.0.0图像处理transformers>=4.40.0版面分析模型torch>=2.0.0深度学习框架python-docx>=1.1.0Word 文档生成七、部署架构1. Docker Compose 配置graph LR Host[宿主机] --> LB[Nginx/Proxy] LB --> App[App 容器] LB --> Ollama[Ollama 容器] App --> DB[(SQLite 数据卷)] App --> Files[uploads 数据卷]2. GPU 加速若有 NVIDIA 显卡，可编辑 docker-compose.yml 取消 deploy 段落的注释以启用 GPU 加速。services: ollama: deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]3. 常用 Docker 命令docker compose down # 停止服务 docker compose up -d # 重新启动（数据不会丢失） docker compose logs -f app # 查看应用日志 docker compose logs -f ollama # 查看 Ollama 日志八、性能参考操作时间说明模型冷启动首次请求~50 秒需加载模型到内存后续单页识别~0.5 秒版面分析 + OCRPDF 渲染取决于页数2x 缩放矩阵渲染整体加速比2.5x相比逐区域 OCR九、常见问题1. 安装问题Ollama 未找到错误信息：Ollama not found解决方法：先安装 Ollama 并确保其在 PATH 中# macOS/Linux curl -fsSL https://ollama.com/install.sh | sh # Windows # 从 https://ollama.com/download 下载安装包模型下载失败解决方法：检查网络连接，手动执行模型拉取ollama pull glm-ocr2. 运行问题OCR 超时可能原因：图片过大或网络问题解决方法：系统已设置 180 秒超时，等待即可检查 Ollama 服务是否正常运行尝试重启服务版面分析失败可能原因：模型未正确加载解决方法：确保已安装 torch 和 transformers检查服务器日志查看具体错误3. 使用问题PDF 拆页不清晰说明：系统使用 2x 缩放矩阵渲染 PDF 以保证 OCR 质量解决方法：如需更高分辨率，可修改 server.py 中的 mat 参数导出的 Word 文档格式问题说明：DOCX 导出基于 python-docx，解析 OCR 结果中的表格和标题解决方法：识别时确保版面分析正确检测到表格区域十、项目结构Folio-OCR/ ├── server.py # FastAPI 后端（单文件） ├── index.html # HTML 页面 ├── script.js # 前端逻辑 ├── style.css # 样式 ├── latex_unicode.json # LaTeX → Unicode 映射表 ├── requirements.txt # Python 依赖 ├── Dockerfile # Docker 镜像构建 ├── docker-compose.yml # Docker Compose 编排 ├── start.bat # Windows 启动脚本 ├── folio_ocr.db # SQLite 数据库（运行时生成） └── uploads/ # 上传文件目录（运行时生成）十一、API 端点方法路径说明GET/前端页面GET/api/status服务状态、Ollama 连通性POST/api/load-model启动 Ollama 并预热模型POST/api/upload上传文件，返回 SSE 页面流GET/api/images/{doc_id}/{filename}获取页面图片POST/api/ocr/{doc_id}/{page_num}单页 OCRPOST/api/ocr/{doc_id}/all批量 OCR 全部页面GET/api/documents列出所有文档GET/api/documents/{doc_id}获取文档详情DELETE/api/documents/{doc_id}删除文档PUT/api/pages/{doc_id}/{page_num}/text保存编辑后的文本POST/api/export/{doc_id}导出 DOCX参考资料Folio-OCR GitHub 仓库GLM-OCR 模型Ollama 官方文档FastAPI 官方文档PP-DocLayoutV3 模型
Axe CLI 工具指南一、概述1. 简介A. 是什么Axe 是一个轻量级的命令行工具，用于运行单用途的 AI 代理。它使用 TOML 配置文件定义代理行为，支持多个 AI 提供商，包括 Anthropic、OpenAI 和 Ollama（本地模型）。B. 为什么学简化 AI 代理的创建和部署流程支持代码版本控制和团队协作提供持久化内存和技能系统支持 MCP（Model Context Protocol）工具扩展C. 学完能做什么使用 TOML 文件定义和管理 AI 代理配置多提供商支持实现代理间的委托调用使用 Docker 容器化部署集成外部 MCP 工具2. 前置知识A. 必备技能基本 Linux 命令行操作了解 TOML 配置文件格式熟悉 Git 版本控制B. 推荐知识Docker 容器基础概念AI API 使用经验MCP 协议基础二、环境准备1. 系统要求Linux、macOS 或 WindowsGo 1.21+（源码编译）Docker（可选，用于容器化部署）2. 安装步骤使用 Homebrew 安装（推荐）：brew install jrswab/tap/axe使用 Go 安装：go install github.com/jrswab/axe@latestDocker 方式：docker pull ghcr.io/jrswab/axe:latest3. 验证安装axe --version axe --help三、核心概念1. 基本术语Agent（代理）：AI 实体，执行特定任务Skill（技能）：可复用的指令集Memory（内存）：持久化的对话历史MCP：Model Context Protocol，工具扩展协议Provider（提供商）：AI 模型服务提供商2. 工作原理graph TB subgraph "配置层" A[agents/*.toml 代理定义] B[skills/SKILL.md 技能指令] C[config.toml 凭证配置] end subgraph "执行层 - Axe CLI" D[运行命令解析] E[上下文构建] F[工具调用] end subgraph "提供商层" G[Anthropic API] H[OpenAI API] I[Ollama 本地模型] end subgraph "存储层" J[持久化内存 timestamped logs] K[工作目录 sandboxed] end A --> D B --> E C --> D D --> E E --> F F --> G F --> H F --> I F --> K J --> E L[stdin 管道输入] --> D M[cron/git hooks] --> D3. 配置目录结构默认配置目录为 $XDG_CONFIG_HOME/axe/，通常为：Linux：~/.config/axe/macOS：~/Library/Application Support/axe/目录结构：~/.config/axe/ ├── agents/ │ └── *.toml # 代理定义文件 ├── skills/ │ └── SKILL.md # 技能指令文件 ├── config.toml # 凭证配置 └── memory/ # 持久化内存日志四、快速上手1. Hello World 示例首先创建配置文件 ~/.config/axe/config.toml：[anthropic] api_key = "your_anthropic_api_key"创建代理定义 ~/.config/axe/agents/greeting.toml：name = "greeting" model = "claude-3-haiku-20240307" provider = "anthropic" [system] prompt = "你是一个友好的助手，用中文回答问题。" [max_tokens] input = 10000 output = 4096运行代理：axe run greeting "你好，请介绍一下自己"2. 核心功能演示管道输入支持：echo "解释这个代码的作用" | axe run coder < main.pyGit hook 集成：axe hook install pre-commit axe hook list axe hook remove pre-commit列出可用代理：axe list3. 代码讲解代理定义说明：name：代理标识符，用于 axe run 命令model：使用的基础模型名称provider：AI 提供商（anthropic、openai、ollama）system.prompt：系统提示词max_tokens：输入输出 token 限制五、进阶内容1. 常用功能子代理委托代理可以调用其他代理，通过深度限制防止无限循环：name = "analyst" model = "claude-3-haiku-20240307" provider = "anthropic" [delegates] max_depth = 3 allow = ["coder", "researcher"]技能系统创建可复用的技能指令 ~/.config/axe/skills/coder/SKILL.md：# 代码审查技能 你是一位资深代码审查专家。审查时请： 1. 检查代码风格一致性 2. 识别潜在 bug 3. 建议性能优化 4. 评估安全性 输出格式： - 问题清单 - 改进建议 - 优先级标注在代理中使用技能：[skills] include = ["coder", "researcher"]持久化内存Axe 自动维护时间戳标记的内存日志，支持垃圾回收：[memory] enabled = true max_age = "30d" # 30 天后自动清理 max_size = "1GB" # 最大存储限制MCP 工具集成配置 MCP 服务器连接：[mcp] mcp.servers name = "filesystem" command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] mcp.servers name = "github" command = "npx" args = ["-y", "@modelcontextprotocol/server-github"] env = { GITHUB_TOKEN = "your_github_token" }2. 最佳实践使用版本控制管理代理配置为不同环境创建不同的代理限制代理调用深度避免无限循环定期清理内存日志使用环境变量存储敏感信息3. 性能优化选择合适的模型平衡速度和质量使用本地 Ollama 模型减少延迟限制输入 token 大小缓存常用查询结果六、Docker 部署1. 场景描述将 Axe 容器化部署，确保环境隔离和可移植性。2. 实现步骤拉取镜像：docker pull ghcr.io/jrswab/axe:latest创建 Dockerfile 自定义构建：FROM ghcr.io/jrswab/axe:latest # 添加自定义配置 COPY config.toml /app/config.toml COPY agents/ /app/agents/ COPY skills/ /app/skills/ # 运行 ENTRYPOINT ["/app/axe"]运行容器：docker run -it \ -v ~/.config/axe:/app/config \ ghcr.io/jrswab/axe:latest \ run greeting "你好"使用 Docker Compose 编排：version: '3.8' services: axe: image: ghcr.io/jrswab/axe:latest volumes: - ./config:/app/config - ./agents:/app/agents - ./skills:/app/skills environment: - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} command: ["run", "coder", "review my code"]3. 安全加固使用只读挂载限制容器资源使用非 root 用户运行定期更新镜像七、常见问题1. 安装问题问题：Homebrew 无法安装解决：使用 Go 安装或 Docker 方式go install github.com/jrswab/axe@latest export PATH=$PATH:$(go env GOPATH)/bin2. 配置问题问题：API 密钥验证失败解决：检查 config.toml 格式和密钥有效性[anthropic] api_key = "sk-ant-xxx" [openai] api_key = "sk-xxx" [ollama] base_url = "http://localhost:11434"3. 运行问题问题：代理响应超时解决：调整超时设置或使用更快的模型[timeout] request = "60s" connect = "10s"八、参考资料参考资料Axe CLI GitHub RepositoryAxe Documentation
Debian 13 修复 Docker 权限与服务问题案例复盘一、事件概述1. 事件背景在 Debian 13（trixie）系统上，Docker 容器化平台出现功能异常，主要表现为权限拒绝和服务单元缺失问题。用户在尝试执行 docker 命令时遇到阻碍，影响正常的容器化开发和部署工作。2. 影响范围A. 影响功能docker ps、docker run 等命令无法正常执行Docker 守护进程无法启动无法进行容器镜像拉取和容器管理B. 影响用户系统管理员 lab 用户，需要使用 Docker 进行应用开发和部署工作3. 严重程度P2 级故障（开发工具功能受阻，不影响生产环境）二、问题分析1. 直接原因通过系统诊断发现三个直接问题：docker-ce 包处于 rc 状态（已删除但配置文件残留）用户 lab 不在 docker 用户组中Docker 守护进程的 systemd 服务单元缺失graph TB A[用户执行 docker ps] --> B{权限检查} B -->|不在 docker 组| C[权限拒绝] B -->|在 docker 组| D{服务检查} D -->|服务未启动| E[连接失败] D -->|服务运行中| F[正常执行] subgraph 根本原因 G[docker-ce 包缺失] H[用户未在 docker 组] I[systemd 服务单元缺失] end G -.导致.-> I H -.导致.-> C I -.导致.-> E2. 根本原因A. docker-ce 包被删除系统中 docker-ce 包的状态为 rc（removed but configuration files remain），这意味着：Docker 守护进程已被卸载只保留了客户端组件 docker-clisystemd 服务单元随之被删除已安装的残留组件：docker-cli（26.1.5+dfsg1）- Docker 客户端docker-buildx-plugin - Buildx 插件docker-compose-plugin - Compose 插件docker-ce-rootless-extras - Rootless 支持包B. 用户权限配置缺失用户 lab 不在 docker 用户组中，导致无法访问 Docker 守护进程的 Unix socket（/var/run/docker.sock）。C. 服务单元缺失由于 docker-ce 包被删除，systemd 服务单元文件 /usr/lib/systemd/system/docker.service 不存在，systemctl 无法找到 docker.service 单元。3. 深层分析问题的深层原因在于系统维护过程中可能发生了以下情况：误操作或自动清理工具移除了 docker-ce 包但未重新安装系统升级或包管理操作导致依赖关系异常用户配置未随环境变化同步更新Docker 架构中的关键依赖关系：docker-ce：包含 Docker 守护进程（dockerd）和 CLIcontainerd：底层容器运行时（系统中已正确安装）docker 用户组：控制 socket 访问权限systemd：服务管理和进程启动graph LR A[用户命令] --> B[docker CLI] B --> C[Docker Socket] C --> D[dockerd 守护进程] D --> E[containerd] E --> F[容器] subgraph 权限控制 G[docker 用户组] -.访问控制.-> C end subgraph 服务管理 H[systemd] -.管理.-> D end三、解决方案1. 重新安装 docker-ce 包# 更新 apt 软件包缓存 sudo apt update # 重新安装 docker-ce sudo apt install docker-ce安装过程中会自动：安装 Docker 守护进程 dockerd安装 systemd 服务单元到 /usr/lib/systemd/system/docker.service替换旧的 docker-cli 为官方的 docker-ce-cli安装完成后验证：dpkg -l | grep docker # 应显示 docker-ce 和 docker-ce-cli 为 ii（已安装）状态2. 启动并启用 Docker 服务# 启动 Docker 服务 sudo systemctl start docker # 设置 Docker 开机自启 sudo systemctl enable docker # 验证服务状态 sudo systemctl status docker预期输出应显示：Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled)Active: active (running)Main PID: dockerd 进程 ID3. 配置用户权限# 将当前用户添加到 docker 组 sudo usermod -aG docker $USER # 验证组添加 groups $USER # 输出中应包含 docker重要提示：添加用户到 docker 组后需要以下操作之一才能生效：退出并重新登录系统或在当前会话中使用 newgrp 切换组环境：newgrp docker4. 功能验证# 测试 Docker 命令（无需 sudo） docker ps # 运行 hello-world 容器验证完整功能 docker run --rm hello-world # 查看 Docker 系统信息 docker info四、验证结果验证项预期结果实际结果docker-ce 安装ii 状态（已安装）✅ 版本 29.3.0服务状态active (running)✅ 运行中开机自启enabled✅ 已启用用户组包含 docker✅ 已添加docker ps成功执行✅ 正常hello-world成功运行✅ 输出欢迎信息最终环境配置：Docker 版本：29.3.0服务单元：/usr/lib/systemd/system/docker.service容器运行时：containerd用户 lab：已加入 docker 组五、经验总结1. 关键要点docker-ce 是核心包，包含守护进程和服务单元，删除会导致 Docker 完全失效Docker socket 权限由 docker 组控制，用户必须在该组中才能访问 Docker APIsystemd 服务单元随 docker-ce 包安装/卸载，不是独立管理的文件2. 最佳实践定期检查关键软件包状态dpkg -l | grep -E "^rc"使用 systemctl 管理服务时，先确认服务单元存在systemctl list-unit-files | grep docker系统维护后及时验证关键服务状态3. 注意事项将用户添加到 docker 组后必须重新登录或使用 newgrp 才能生效docker-ce 和 docker-ce-cli 由官方仓库提供，与系统的 docker-cli 可能冲突Debian 13 使用 containerd 作为默认容器运行时，Docker 安装后会自动连接六、预防措施建立包状态定期检查机制，发现 rc 状态的包及时处理对关键服务建立监控告警，服务异常时及时通知记录系统维护操作，便于问题追溯和快速定位参考资料Docker 官方文档 - 安装指南Debian Package Management - dpkg 状态码说明
Docker 环境检查与验证一、系统环境1. 系统信息A. 发行版信息PRETTY_NAME="Debian GNU/Linux 13 (trixie)"NAME="Debian GNU/Linux"VERSION_ID="13"VERSION="13 (trixie)"VERSION_CODENAME=trixieDEBIAN_VERSION_FULL=13.3ID=debianB. 内核版本6.12.63+deb13-amd642. Docker 环境状态Docker version 29.3.0, build 5927d803. Docker Compose 版本Docker Compose version v5.1.0二、Docker 服务状态服务状态：active（运行中）三、功能验证1. Hello World 测试A. 测试过程使用 docker run hello-world 命令进行验证。该命令会从 Docker Hub 拉取 hello-world 镜像并运行容器。B. 测试结果测试成功完成。Docker 客户端成功连接到守护进程，拉取镜像并输出欢迎信息，验证了 Docker 环境的完整性和功能正常。四、可用命令参考1. Docker 基础命令docker version：查看 Docker 版本信息docker info：显示系统级信息docker images：列出本地镜像docker ps：列出运行中的容器docker ps -a：列出所有容器docker run：运行容器docker stop：停止容器docker rm：删除容器docker rmi：删除镜像docker logs：查看容器日志2. Docker Compose 命令docker compose version：查看 Docker Compose 版本docker compose up：创建并启动服务docker compose down：停止并移除容器docker compose ps：列出容器docker compose logs：查看服务日志docker compose exec：在服务中执行命令参考资料
Debian 系统下安装 Node.js 和修复 Docker 服务一、概述1. 简介本文介绍在 Debian 13 (trixie) 系统上安装 Node.js 以及修复 Docker 守护进程无法运行的问题。2. 为什么学Node.js 是前端开发和服务端 JavaScript 运行的必备环境Docker 是容器化部署的核心工具，需要正确配置才能使用了解 Docker 的 CLI 和 Engine 组件区别有助于问题排查3. 学完能做什么在 Debian 系统上安装 Node.js 20 LTS诊断并修复 Docker 守护进程未运行的问题理解 Docker 的安装结构和 systemd 服务管理二、环境准备1. 系统要求操作系统：Debian GNU/Linux 13 (trixie) 或兼容版本权限：需要 sudo 权限执行系统级命令网络：需要访问 NodeSource 仓库和 Docker 官方仓库2. 安装前检查检查系统版本：cat /etc/os-release | grep PRETTY_NAME检查 Node.js 是否已安装：which node && node --version || echo "Node.js 未安装"检查 Docker 安装状态：which docker && docker --version docker ps三、问题分析1. Docker 守护进程未运行A. 现象描述执行 docker ps 命令时报错：Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?B. 根本原因Docker 由两个主要组件组成：Docker CLI：命令行客户端，用于发送命令给守护进程Docker Engine (docker-ce)：守护进程，负责实际执行容器操作本例中：Docker CLI 已安装 (版本 26.1.5)Docker Engine (docker-ce) 处于 rc 状态，表示已被移除但配置文件保留缺少 Docker Engine 导致无法启动守护进程graph TD A[用户执行 docker ps] --> B[Docker CLI] B -->|Unix socket| C{Docker Engine} C -->|存在| D[正常执行] C -->|不存在| E[连接失败] E --> F[报错: Cannot connect to daemon]C. 诊断方法查看已安装的 Docker 相关软件包：dpkg -l | grep -i docker输出示例：ii docker-cli 26.1.5+dfsg1-9+b11 amd64 Linux container runtime -- client rc docker-ce 5:29.3.0-1~debian.12~bookworm amd64 Docker: the open-source application container engineii 表示已安装rc 表示已移除但配置保留尝试启动 Docker 服务：sudo systemctl start docker若报错 Unit docker.socket not found，说明缺少 Docker Engine。2. Debian 13 与 Docker 仓库Docker 官方仓库主要针对 Debian 12 (bookworm) 构建，但在 Debian 13 上仍可正常工作。系统已配置 Docker 官方仓库的 bookworm 源。四、解决方案1. 安装 Node.js 20 LTSA. 使用 NodeSource 仓库NodeSource 提供 Node.js 的 APT 仓库，支持多种 Debian/Ubuntu 版本。添加 NodeSource 仓库：curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -安装 Node.js：sudo apt-get install -y nodejsB. 验证安装检查 Node.js 版本：node --version检查 npm 版本：npm --version预期输出：v20.20.1 10.8.22. 修复 Docker 服务A. 重新安装 Docker Engine安装完整的 Docker 组件：sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin说明：docker-ce：Docker Engine 核心组件docker-ce-cli：Docker CLI 命令行工具containerd.io：容器运行时docker-buildx-plugin：多平台构建插件docker-compose-plugin：Docker Compose V2 插件B. 启动 Docker 服务启动 Docker 守护进程：sudo systemctl start docker设置开机自启：sudo systemctl enable docker检查服务状态：sudo systemctl status docker --no-pager预期输出中应包含：Active: active (running)C. 验证 Docker 功能运行测试容器：docker ps若无报错且显示容器列表，表示 Docker 正常工作。3. Docker 服务架构Docker 在 systemd 下的运行机制：graph TB A[systemd] -->|启动| B[docker.service] B -->|触发| C[docker.socket] B -->|管理| D[dockerd 守护进程] D -->|监听| E[/run/docker.sock] F[docker CLI] -->|连接| E E -->|命令| D关键组件：docker.service：systemd 服务单元，管理 dockerd 进程docker.socket：socket 激活单元，按需启动服务dockerd：Docker 守护进程，通过 Unix socket /run/docker.sock 接收命令/run/docker.sock：Unix socket 文件，CLI 与守护进程的通信通道五、最终结果安装完成后，各组件版本如下：组件版本状态Node.jsv20.20.1✅ 已安装npm10.8.2✅ 已安装Docker Engine29.3.0✅ 运行中Docker CLI29.3.0✅ 已安装docker-compose5.1.0 (V2)✅ 已安装containerd2.2.1✅ 运行中六、技术要点1. Docker 组件区分组件作用必要性docker-ceDocker Engine 核心组件必须docker-ce-cli命令行客户端必须containerd.io容器运行时必须docker-buildx-plugin多平台构建可选docker-compose-plugin容器编排可选仅安装 CLI 而不安装 Engine 是无效的，两者缺一不可。2. Overlay2 存储驱动Docker 使用 overlay2 作为默认存储驱动，这是推荐的性能最佳选项：支持分层存储，节省磁盘空间读写性能优异广泛支持 Linux 内核查看存储驱动类型：docker info | grep "Storage Driver"3. nftables 警告处理首次启动 Docker 时可能看到类似日志：level=info msg="Deleting nftables IPv4 rules" error="exit status 1"这是 Docker 尝试清理旧的防火墙规则，若无旧规则则报错。此警告不影响 Docker 正常运行，可以忽略。4. Node.js LTS 版本Node.js 20.20.1 是 Iron LTS 版本，官方支持至 2026 年 4 月，适合生产环境使用。LTS 版本特点：长期支持，稳定性高安全更新持续提供适合企业级应用七、常见问题1. Docker 服务启动失败问题现象执行 systemctl start docker 后服务未启动。排查步骤查看服务状态详情：sudo systemctl status docker -l查看服务日志：sudo journalctl -u docker.service -n 50 --no-pager常见原因及解决原因 1：端口被占用sudo netstat -tulpn | grep :2375原因 2：存储空间不足df -h原因 3：权限问题sudo chown -R root:root /var/run/docker.sock2. Node.js 安装失败问题现象NodeSource 仓库添加失败或包无法下载。解决方法检查网络连接：curl -I https://deb.nodesource.com手动添加 GPG 密钥：curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg3. docker 权限问题问题现象每次使用 docker 命令都需要 sudo。解决方法将当前用户添加到 docker 组：sudo usermod -aG docker $USER注销并重新登录生效，或执行：newgrp docker验证：docker ps八、参考资料NodeSource 官方文档Docker 官方安装文档Docker Engine 架构说明
Docker 守护进程启动失败排查复盘一、事件概述1. 事件背景在主机 192.168.124.80（olab-ops-app）上执行 docker ps 时出现无法连接 Docker 守护进程的报错，需排查根因并恢复服务。2. 影响范围A. 影响用户数使用该节点上的 Docker 服务的用户或应用。B. 影响时长从服务异常到完成修复的窗口期。C. 影响功能无法执行 docker ps、docker run 等所有 Docker 客户端命令依赖该机 Docker 的容器化应用无法启动或管理3. 严重程度该节点上 Docker 不可用，属单机级故障；若为生产节点则严重程度高。二、事件时间线1. 故障现象A. 现象描述在 192.168.124.80 上执行：docker ps报错：Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?B. 初步判断客户端无法连接到 Docker 守护进程，通常表示 dockerd 未正常启动或 socket 不可用。2. 问题发现与诊断A. 检查服务状态执行 systemctl status docker，得到：Active: failed (Result: exit-code)Process: ExecStart=/usr/sbin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock（code=exited, status=203/EXEC）status=203/EXEC 表示 systemd 无法执行所配置的二进制（如路径错误或无可执行权限）。B. 核对可执行文件路径which dockerd 显示实际路径为：/usr/bin/dockerddocker.service 中 ExecStart 配置为：/usr/sbin/dockerd结论：配置路径与真实路径不一致，导致 203/EXEC，Docker 服务无法启动。3. 根本解决A. 解决方案将 /etc/systemd/system/docker.service 中的 ExecStart 由 /usr/sbin/dockerd 修改为 /usr/bin/dockerd，执行 daemon-reload 后启动 docker 服务。B. 验证结果systemctl start docker 成功，docker.service 为 active (running)docker ps 可正常执行（当前无运行中容器时列表为空）flowchart LR A[docker ps 报错] --> B[查看 systemctl status] B --> C[发现 203/EXEC] C --> D[核对 which dockerd] D --> E[修正 service 中路径] E --> F[daemon-reload 并 start] F --> G[恢复正常]三、问题分析1. 直接原因docker.service 中 ExecStart 指向 /usr/sbin/dockerd，而本机 dockerd 实际安装在 /usr/bin/dockerd，systemd 执行失败并报 203/EXEC，Docker 守护进程从未成功启动。2. 根本原因（简要 5 Whys）A. 为什么会出现路径不一致？可能原因包括：通过包管理器安装的 Docker 将 unit 文件放在 /etc/systemd/system/ 并写死为 /usr/sbin/dockerd，而后续用二进制或其它方式安装的 dockerd 放在 /usr/bin/；或不同发行版/安装方式对 FHS 的约定不同。B. 为什么没有更早发现？日常若仅使用 docker 命令且未重启或未主动检查 docker.service 状态，问题会一直潜伏直到需要连接 daemon 时暴露。C. 为什么没有自动恢复？服务因 203/EXEC 启动失败，systemd 不会自动修正 unit 中的路径，需人工修改配置并重新加载。3. 深层反思自定义或覆盖安装的 unit 文件应使用可执行文件的实际路径（或 PATH 中的命令名），避免写死 /usr/sbin。关键节点在变更（如升级、重装 Docker）后应做一次 systemctl status docker 与 docker ps 的简单验证。四、解决方案1. 临时方案A. 实施措施修改 docker.service 中 ExecStart 为 /usr/bin/dockerd，执行：sed -i 's|ExecStart=/usr/sbin/dockerd|ExecStart=/usr/bin/dockerd|' /etc/systemd/system/docker.service systemctl daemon-reload systemctl start dockerB. 效果评估Docker 服务立即恢复，docker ps 等命令恢复正常。2. 永久方案A. 改进措施保持 ExecStart 使用实际路径 /usr/bin/dockerd（或使用 which dockerd 的结果），避免依赖 /usr/sbin。若使用 Ansible/Puppet 等自动化管理，将 dockerd 路径作为变量或事实写入 unit 模板，避免硬编码。B. 实施计划已在 192.168.124.80 完成修改并验证；其它使用相同 unit 的节点可一并检查并统一为实际路径。3. 预防措施部署或升级 Docker 后，将「systemctl status docker」与「docker ps」纳入发布检查清单。对自定义 unit 做代码审查，确保 ExecStart 与当前安装路径一致。五、经验总结1. 做得好的地方从报错信息快速定位到「daemon 未运行」，再通过 systemd 状态和 203/EXEC 缩小到「可执行文件执行失败」。通过 which dockerd 与 unit 内容对比，快速确认路径不一致并一次性修复。2. 需要改进的地方若有多台同架构节点，可增加批量检查脚本，避免同类问题重复出现。3. 流程优化建议将「Docker 安装/升级后验证」写入运维手册或 Runbook，便于复现与交接。参考资料本文为实战排查记录，无外部引用链接。
summary: 'Cross-platform binary build using Docker for mcporter: builds all platform binaries in an isolated container.'read_when:'Building mcporter binaries for multiple platforms''Need to build without installing Bun locally''Want reproducible, isolated builds'Docker Cross-Platform BuildMCPorter provides a Docker-based build script that creates cross-platform binaries in an isolated container. This ensures consistent build environments and prevents local system pollution.Quick Start# Run the Docker build script ./docker_build.sh # Or use pnpm pnpm build:dockerBuild TargetsPlatformArchitectureTargetOutputLinuxamd64bun-linux-x64mcporter-linux-amd64Linuxarm64bun-linux-aarch64mcporter-linux-arm64macOSamd64bun-darwin-x64mcporter-macos-amd64macOSarm64bun-darwin-aarch64mcporter-macos-arm64Windowsamd64bun-windows-x64mcporter-windows-amd64.exeWindowsarm64bun-windows-aarch64mcporter-windows-arm64.exePrerequisitesDocker installed and runningAccess to Docker Hub (to pull oven/bun:latest image)Write permissions to project directoryOutput DirectoryAll binaries are output to the build/ directory in the project root:build/ ├── mcporter-linux-amd64 ├── mcporter-linux-arm64 ├── mcporter-macos-amd64 ├── mcporter-macos-arm64 ├── mcporter-windows-amd64.exe └── mcporter-windows-arm64.exeDocker ImageThe script uses the official oven/bun:latest image, which includes:Latest Bun runtimeBuild dependencies for all target platformsMinimal Debian base (~200MB)The image is pulled automatically on first run and cached for subsequent builds.Script InternalsThe Docker container performs:Mount the project directory as /workspaceInstall dependencies via bun installBuild each target using bun scripts/build-bun.tsOutput binaries to /workspace/build/ (mapped to host build/)Container is cleaned up automatically (--rm flag) after build completes.VerificationAfter building, verify the output:# Check output files ls -lh build/ # Test Linux binary ./build/mcporter-linux-amd64 --version # Verify static linking (Linux) ldd build/mcporter-linux-amd64 # Should output: "not a dynamic executable"Local vs Docker BuildFeaturebuild.sh (Local)docker_build.sh (Docker)Requires Bun installedYesNoOutput directorydist-bun/build/Build environmentHost systemIsolated containerReproducibilityDepends on hostConsistentStartup costInstantFirst run: pull imageCustomizationTo customize the build:Change Docker image: Edit DOCKER_IMAGE in docker_build.shModify targets: Edit the TARGETS arrayAdd flags: Pass additional arguments to bun scripts/build-bun.tsExample for single-target build:docker run --rm \ -v "$PWD:/workspace" \ -w /workspace \ oven/bun:latest \ bash -c ' bun install bun scripts/build-bun.ts \ --target bun-linux-x64 \ --output build/mcporter-linux-amd64 '