next-socks5 轻量级 SOCKS5 服务器实战指南一、概述1. 简介A. 是什么next-socks5 是一个用 Rust 语言编写的轻量级、高性能 SOCKS5 代理服务器，完全遵循 RFC 1928 和 RFC 1929 标准。它提供实时终端仪表板（TUI）和无头模式，适用于容器化部署，采用安全优先的设计理念。B. 为什么使用纯 Rust 实现，无 C 语言依赖，安全性高极低的资源占用和出色的性能表现提供实时可视化的监控仪表板原生支持容器化部署，适合云原生环境开箱即用的安全配置，默认防护 SSRF 攻击C. 使用场景搭建个人或团队的内网代理服务容器化环境中的网络代理解决方案需要实时监控的代理服务部署对安全性有较高要求的生产环境2. 前置知识A. 必备技能基本 Linux 命令行操作了解网络基础概念（TCP、UDP、IPv4/IPv6）了解 SOCKS5 代理协议基础B. 推荐知识Docker 容器基础操作systemd 服务管理TOML 配置文件格式二、环境准备1. 系统要求Linux：支持 musl libc 的 x86_64 或 aarch64 架构Docker：支持 Linux/amd64 和 Linux/arm64 架构macOS 和 Windows：可通过 Docker 运行2. 安装方式一键安装（推荐）使用官方提供的安装脚本，自动选择二进制或 Docker 部署：curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh | shDocker 安装curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --method docker --auth --port 1080手动下载二进制从 GitHub Releases 页面下载预编译的静态二进制文件：curl -fL -o next-socks5.tar.gz \ https://github.com/ZingerLittleBee/next-socks5/releases/latest/download/next-socks5-x86_64-unknown-linux-musl.tar.gz tar xzf next-socks5.tar.gz ./next-socks5-x86_64-unknown-linux-musl/next-socks5 serve --no-tui --listen 0.0.0.0:1080从源码编译git clone https://github.com/ZingerLittleBee/next-socks5 cd next-socks5 cargo build --release ./target/release/next-socks5 serve三、核心概念1. SOCKS5 协议基础SOCKS5 是一个代理协议，支持以下命令：CONNECT：建立 TCP 连接UDP ASSOCIATE：建立 UDP 关联BIND：已明确拒绝（设计决策）2. 认证方式无认证（No-Auth，0x00）：开放代理模式用户名密码认证（Username/Password，0x02）：RFC 1929 标准GSSAPI（0x01）：未实现（与大多数实现一致）3. 地址类型支持IPv4（ATYP 0x01）IPv6（ATYP 0x04）域名（ATYP 0x03）服务器支持服务端 DNS 解析，适用于 CONNECT 和 UDP 目标。4. 系统架构graph TD A[SOCKS5 客户端] -->|TCP 连接| B[SOCKS5 服务器] B -->|认证| C{认证模块} C -->|成功| D[请求处理] C -->|失败| E[拒绝连接] D --> F[CONNECT 中继] D --> G[UDP ASSOCIATE] F --> H[目标服务器] G --> H B --> I[TUI 仪表板] B --> J[日志输出]四、快速上手1. Hello World 示例启动无认证代理./install.sh --no-auth --port 1080启动带认证的代理./install.sh --auth --user alice --pass secret --port 10802. 测试代理测试无认证代理curl --socks5 127.0.0.1:1080 https://example.com测试带认证的代理curl --socks5 alice:secret@127.0.0.1:1080 https://example.com3. 查看仪表板直接启动（带 TUI）next-socks5 serve --listen 127.0.0.1:1080附加到运行中的服务next-socks5 attach五、配置详解1. 基本配置创建配置文件 config.toml：listen = "0.0.0.0:1080" [auth] method = "password" auth.users username = "alice" password = "secret" auth.users username = "bob" password = "hunter2" [timeouts] handshake_ms = 10000 connect_ms = 10000 tcp_idle_ms = 300000 udp_idle_ms = 60000 [limits] max_connections = 2048 max_per_ip = 64 [admin] enabled = true2. 高级配置出站过滤（默认启用）默认情况下，代理拒绝转发到以下地址：回环地址（127.0.0.0/8）链路本地地址（169.254.0.0/16）私有地址（RFC1918）如需访问内网目标，需显式配置：[egress] # 允访问内网地址 allow_loopback = true allow_private = trueUDP 中继配置适用于 NAT 或 Docker 环境：[udp] port_range = "40000-40100" advertise = "203.0.113.42"3. 配置优先级CLI 参数 > 配置文件 > 默认值# CLI 参数覆盖配置文件 next-socks5 serve --config config.toml --listen 0.0.0.0:1080六、部署方案1. systemd 部署使用安装脚本自动创建 systemd 服务：./install.sh --auth --user myuser --pass mypassword --port 1080服务管理命令：systemctl status next-socks5 systemctl start next-socks5 systemctl stop next-socks5 systemctl restart next-socks52. Docker 部署使用 Docker Compose创建 docker-compose.yml：services: next-socks5: image: ghcr.io/zingerlittlebee/next-socks5:latest container_name: next-socks5 restart: unless-stopped network_mode: host volumes: - ./config.toml:/etc/next-socks5/config.toml:ro tmpfs: - /run/next-socks5 command: ["--config", "/etc/next-socks5/config.toml"]启动服务：docker compose up -d使用 Docker Rundocker run -d --name next-socks5 --network host \ -v "$PWD/config.toml:/etc/next-socks5/config.toml:ro" \ ghcr.io/zingerlittlebee/next-socks5:latest \ --config /etc/next-socks5/config.toml3. 防火墙配置UFWufw allow 1080/tcp && ufw allow 40000:40100/udpiptablesiptables -A INPUT -p tcp --dport 1080 -j ACCEPT iptables -A INPUT -p udp --dport 40000:40100 -j ACCEPTnftablesnft add rule inet filter input tcp dport 1080 accept nft add rule inet filter input udp dport 40000-40100 accept七、监控与运维1. TUI 仪表板功能仪表板提供以下功能：实时吞吐量显示（带 30 秒趋势图）成功/错误统计可排序的活动连接表可滚动的日志查看键盘操作按键功能Tab切换滚动焦点（连接表/日志）s循环切换连接排序键↑/↓ 或 k/j滚动一行PgUp/PgDn滚动一屏q 或 Ctrl-C退出2. 日志管理无头模式日志next-socks5 serve --no-tui --config config.toml附加到运行服务# 本地附加 next-socks5 attach # Docker 容器内附加 docker exec -it next-socks5 next-socks5 attach3. 性能监控在单核 4 核云虚拟机上：吞吐量：约 2 GB/s增加延迟：约 1.6 ms新连接速率：约 6000 连接/秒八、安全最佳实践1. 认证配置生产环境建议始终启用用户名密码认证使用强密码（至少 20 位）定期轮换凭证限制单 IP 最大连接数[auth] method = "password" auth.users username = "secure_user" password = "very_long_random_password_here" [limits] max_per_ip = 642. 网络安全防火墙规则仅开放必要端口限制来源 IP 范围使用 fail2ban 防护暴力破解出站过滤保持默认的出站过滤启用状态，除非有明确需求：[egress] # 默认过滤已启用，无需额外配置 # 如需访问内网，显式配置允许的地址3. 运行安全最小权限原则使用非特权用户运行限制配置文件权限保护管理员 Socket# 创建专用用户 useradd -r -s /bin/false next-socks5九、故障排查1. 常见问题UDP 关联失败症状：TCP 连接正常，UDP 不工作原因：NAT/端口映射配置错误解决：使用 host 网络模式或正确配置 advertise 地址认证失败症状：客户端收到 0x01 错误码原因：用户名密码错误或认证方法不匹配解决：检查配置文件中的凭证连接被拒绝症状：收到 0x02 或 0x05 错误码原因：达到连接限制或目标不可达解决：调整 limits 参数或检查网络连通性2. 调试模式使用 mock 模式测试仪表板：next-socks5 serve --listen 127.0.0.1:1080 --mock3. 日志级别无头模式下输出详细日志：next-socks5 serve --no-tui --config config.toml十、性能优化1. 连接限制配置根据服务器规格调整：[limits] max_connections = 2048 # 根据文件描述符限制调整 max_per_ip = 64 # 防止单个客户端占用资源2. 超时设置根据网络环境优化：[timeouts] handshake_ms = 10000 # 握手超时，防止慢速攻击 connect_ms = 10000 # 连接超时 tcp_idle_ms = 300000 # TCP 空闲超时（5 分钟） udp_idle_ms = 60000 # UDP 空闲超时（1 分钟）3. 系统参数调优增加文件描述符限制# 临时调整 ulimit -n 65536 # 永久调整（/etc/security/limits.conf） next-socks5 soft nofile 65536 next-socks5 hard nofile 65536十一、实战案例1. 搭建团队代理服务需求描述为一个小型团队搭建 SOCKS5 代理服务，支持多用户、带认证、提供实时监控。实现步骤创建配置文件：listen = "0.0.0.0:1080" [auth] method = "password" auth.users username = "alice" password = "alice_secure_password" auth.users username = "bob" password = "bob_secure_password" auth.users username = "charlie" password = "charlie_secure_password" [timeouts] handshake_ms = 10000 connect_ms = 10000 tcp_idle_ms = 300000 udp_idle_ms = 60000 [limits] max_connections = 1024 max_per_ip = 32 [udp] port_range = "40000-40100" [admin] enabled = true使用 Docker Compose 部署：curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --method docker --auth --port 1080配置防火墙：ufw allow 1080/tcp ufw allow 40000:40100/udp监控服务：# 附加到运行中的容器查看仪表板 docker exec -it next-socks5 next-socks5 attach2. 容器化环境部署需求描述在 Kubernetes 环境中部署 SOCKS5 代理服务。实现步骤创建 ConfigMap：apiVersion: v1 kind: ConfigMap metadata: name: socks5-config data: config.toml: | listen = "0.0.0.0:1080" [auth] method = "password" auth.users username = "service_user" password = "secure_password" [limits] max_connections = 512 max_per_ip = 64创建 Deployment：apiVersion: apps/v1 kind: Deployment metadata: name: next-socks5 spec: replicas: 2 selector: matchLabels: app: next-socks5 template: metadata: labels: app: next-socks5 spec: containers: - name: next-socks5 image: ghcr.io/zingerlittlebee/next-socks5:latest command: ["next-socks5", "serve", "--no-tui", "--config", "/etc/next-socks5/config.toml"] volumeMounts: - name: config mountPath: /etc/next-socks5 ports: - containerPort: 1080 protocol: TCP volumes: - name: config configMap: name: socks5-config创建 Service：apiVersion: v1 kind: Service metadata: name: next-socks5 spec: selector: app: next-socks5 ports: - port: 1080 targetPort: 1080 protocol: TCP type: LoadBalancer十二、参考资料参考资料next-socks5 GitHub 仓库RFC 1928 - SOCKS Protocol Version 5RFC 1929 - Username/Password Authentication for SOCKS V5
Kubernetes 节点根分区磁盘占用过高排查复盘
Kubernetes 节点根分区磁盘占用过高排查复盘一、事件概述1. 事件背景2026 年 7 月 15 日上午，监控发现 K8s 工作节点 zcyun-k8s-node5（IP：10.10.184.204）根分区使用率持续攀升至 89%，逼近告警阈值，存在磁盘写满导致节点上所有 Pod 业务中断的风险。该节点承载物联网（IoT）数据、规则引擎、设备管理等核心服务。2. 影响范围A. 影响资源节点根分区 /dev/vda1（总容量 40G，已用 34G，剩余 4.5G）B. 风险等级P2 级（尚未触发业务故障，但距离写满仅一步之遥）C. 潜在影响若根分区写满，将导致节点上 28 个容器无法写入日志与临时数据，引发服务大面积异常、数据库连接失败、Pod 被驱逐等连锁问题。3. 处理结果经排查定位并处置后，根分区使用率从 89% 下降至 23%，释放约 25G 空间，节点恢复正常水位。二、排查过程1. 排查思路磁盘使用率过高的问题，按「先排除 inode 耗尽，再定位大文件归属，最后定位到具体文件」的层级化思路推进，整体决策流程如下。graph TD A["df 显示根分区 89%"] --> B{"inode 使用率?"} B -->|"仅 5%"| C["排除碎文件问题 锁定大文件"] C --> D["du 逐层定位 /var 29G"] D --> E["/var/lib/docker 24G overlay2 可写层"] E --> F["docker system df Containers 22.6G"] F --> G["docker ps -s 定位容器"] G --> H["iot-data 11.4G iot-rule 10.9G"] H --> I["进入容器可写层 UpperDir"] I --> J["rocketmq_client.log 10 份 1.1G 归档"] J --> K["根因锁定"]2. 步骤一：确认磁盘与 inode 状态首先通过 df 命令确认磁盘整体情况，并检查 inode 使用率以排除「小文件过多导致 inode 耗尽」的可能。df -h # 根分区 40G，已用 34G，89% df -i # inode 仅使用 5%结论：inode 使用率仅 5%，排除碎文件问题，判定为「少数大文件」占用空间。3. 步骤二：逐层定位大目录使用 du 命令从根目录逐层向下统计，定位空间占用大头。du -hx --max-depth=1 / # /var 29G du -hx --max-depth=1 /var # /var/lib 24G du -hx --max-depth=1 /var/lib # /var/lib/docker 24G结论：/var/lib/docker 占用 24G，其中 overlay2 目录为最大头；镜像本身仅 2.8G，说明问题出在容器运行时数据。4. 步骤三：区分镜像与容器可写层通过 docker system df 区分镜像缓存与容器可写层占用。docker system df关键发现：Containers 项 SIZE 为 22.61GB，但 RECLAIMABLE 为 0。这意味着占用来自「容器运行时写入可写层」的数据，而非镜像缓存，因此常规的 docker prune 清理无效。5. 步骤四：定位到具体容器通过 docker ps -s 查看每个容器可写层大小，按体积排序。docker ps -s --format 'table {{.Size}}\t{{.Names}}\t{{.Image}}'定位到两个异常容器：容器可写层大小镜像xcloud-srv-iot-data11.4Gnew-iot/xcloud-srv-iot-dataxcloud-srv-iot-rule10.9Gnew-iot/xcloud-srv-iot-rule两者合计约 22G，与容器总占用 22.61G 完全吻合。6. 步骤五：进入可写层定位具体文件通过 docker inspect 获取容器可写层路径（UpperDir），直接查看其中写入的大文件。docker inspect <容器名> --format '{{.GraphDriver.Data.UpperDir}}' # /var/lib/docker/overlay2/<hash>/diff在两个容器的 /root/logs/rocketmqlogs/ 目录下，均发现大量 RocketMQ 客户端日志：文件大小rocketmq_client.log.1 ~ rocketmq_client.log.10每份 1.1Grocketmq_client.log（当前写入）191M ~ 653M7. 步骤六：分析日志内容确认根因查看当前日志文件内容，发现全是 RocketMQ 客户端在 INFO 级别高频打印的持久化日志。2026-07-15 08:49:56 INFO RocketmqClient - [persistAll] Group: iot-data-online-g updateConsumeOffsetToBroker MessageQueue [topic=iot-device-online-changed, brokerName=broker-a, queueId=0] 16020日志在同一毫秒内针对每个 MessageQueue 打印一条，由于该服务订阅了多 topic、多 group、多 queueId、双 broker，每次心跳与持久化周期都会刷出大量 INFO 行，导致日志文件持续膨胀。三、根因分析1. 磁盘占用构成根分区 34G 占用的构成关系如下图所示，容器可写层中的 RocketMQ 日志占据了绝对主体。graph LR A["/dev/vda1 占用 34G"] --> B["容器可写层 22G"] A --> C["journald 日志 3.9G"] A --> D["镜像层 2.8G"] A --> E["系统与其它 5.3G"] B --> B1["iot-data RocketMQ 日志 11.4G"] B --> B2["iot-rule RocketMQ 日志 10.9G"]2. 直接原因两个 IoT 服务容器内嵌的 RocketMQ 客户端，在默认 INFO 日志级别下高频打印 persistAll 与 updateConsumeOffsetToBroker 日志；日志写入容器可写层（overlay2 的 UpperDir），单文件上限 1G、滚动保留 10 份，导致每个容器稳定占用约 11G。3. 根本原因（5 Whys 分析）A. 为什么磁盘占用这么高？两个容器的 RocketMQ 客户端日志累积到约 22G。B. 为什么日志会累积到这么大量？客户端日志级别配置为默认的 INFO，而该级别下会按 MessageQueue 维度高频打印持久化日志。C. 为什么已有的定时清理没有生效？原有的 clearDockerLog.sh 脚本只清理 /var/lib/docker/containers/ 下的 stdout 日志（json.log），而 stdout 日志全机仅 1M；真正的元凶是容器可写层内的应用日志，原脚本完全不涉及。D. 为什么日志写在容器可写层而非挂载卷？应用将日志输出到容器内 /root/logs 目录，未通过 emptyDir、hostPath 或 PVC 挂载到独立存储，也未接入 logrotate 轮转。E. 为什么客户端日志级别未做约束？RocketMQ 客户端默认日志级别为 INFO，应用启动参数未通过 -Drocketmq.client.logLevel 显式调低，缺少日志治理规范。4. 深层反思容器可写层本质是临时存储，不应承载业务日志。日志要么输出到 stdout 由容器运行时统一接管并轮转，要么挂载到独立卷并配置切分。本次问题暴露了日志治理与容器存储规范的双重缺失。四、解决方案1. 临时方案：优化定时清理脚本对原有 clearDockerLog.sh 脚本进行增强，使其覆盖三类元凶，并复用已有的 cron 任务（/etc/cron.d/logclear，每 10 分钟执行一次）。清理脚本的核心逻辑如下：# 1) 容器 stdout 日志（原有功能） find /var/lib/docker/containers/ -type f -name '*-json.log' | while read f; do : > "$f"; done # 2) 容器可写层内的应用日志（新增，命中本次根因） docker ps -q | while read cid; do upper=$(docker inspect "$cid" -f '{{.GraphDriver.Data.UpperDir}}') # 已轮转归档日志：直接 rm 立即释放（不被进程持有） find "$upper" -type f \( -name '*.log.[0-9]*' -o -name '*log*.gz' \) -exec rm -f {} \; # 当前写入的大日志：truncate 清空 find "$upper" -type f -name '*.log' -size +50M -exec sh -c ': > "$1"' _ {} \; done # 3) journald 系统日志（新增） journalctl --vacuum-size=200M执行后效果：overlay2 占用从 24G 降至 7.5G，docker system df 的 Containers 从 22.6G 降至 1.1G。2. 一个关键坑：df 显示滞后清理归档日志后，df 一度仍显示 77% 使用率，而 du 与 docker system df 都显示真实占用仅 8.6G。经过多轮排查（排除 deleted-but-open 文件、mmap 映射、孤儿块、保留块后），最终定位为 Linux 内核在大量文件删除后的块使用统计延迟（VFS lazy accounting）。sync && echo 3 > /proc/sys/vm/drop_caches # 刷新内核统计 df -h / # 立即显示真实值 23%sequenceDiagram participant U as 运维 participant S as 服务器 participant D as Docker participant C as 清理脚本 U->>S: df 发现根分区 89% U->>S: du 逐层定位 S-->>U: /var/lib/docker 24G U->>D: docker ps -s 定位容器 D-->>U: iot-data / iot-rule 共 22G U->>S: 查看可写层日志 S-->>U: RocketMQ 日志爆炸 U->>C: 优化清理脚本并手动执行 C-->>S: 删除归档 + vacuum journal U->>S: df 仍显示 77%（统计延迟） U->>S: sync + drop_caches S-->>U: 真实使用率 23%经验：清理大文件后若 df 未及时下降，应先执行 sync 与 drop_caches 刷新内核统计，避免误判为文件残留或文件系统损坏，切勿贸然 fsck。3. 永久方案：从源头治理日志定时清理只是兜底，RocketMQ 日志仍会持续产生。根治需从应用侧入手，在启动参数中调低客户端日志级别：-Drocketmq.client.logLevel=WARN调整后，INFO 级别的 persistAll 刷屏日志将停止输出，从源头杜绝日志膨胀。4. 预防措施A. 日志治理规范业务日志统一输出到 stdout，由容器运行时接管并配置 json 日志轮转（max-size、max-file）若需文件日志，必须挂载到 emptyDir 或独立卷，并接入 logrotateB. 监控告警前置对节点磁盘使用率设置分级告警（如 75% 预警、85% 紧急）纳入容器可写层增长监控，及时发现异常写入的 PodC. 清理脚本完善保留增强后的清理脚本作为兜底机制，但应明确其仅处理症状，根治仍依赖应用侧日志级别调整。五、经验总结1. 排查方法论inode 优先：磁盘高占用先查 df -i，快速区分「碎文件」与「大文件」两类问题层级化定位：du 逐层缩小范围，再用 docker system df 区分镜像与可写层docker prune 的局限：RECLAIMABLE 为 0 表示占用在运行时可写层，prune 无效，需从可写层入手2. 关键认知A. 容器可写层非持久存储可写层（overlay2 UpperDir）随容器生命周期存在，不应承载重要日志。容器删除重建后可写层即清空，这也提供了一种「重置可写层」的应急手段。B. stdout 日志与可写层日志是两回事/var/lib/docker/containers/ 下的 json 日志是容器标准输出，而应用写到的容器内文件落在可写层，两者清理方式完全不同。排查时需明确区分。C. df 统计可能滞后大量删除文件后，df 的使用率可能因内核统计延迟而不准确，需结合 du、docker system df 交叉验证，必要时 sync + drop_caches 刷新。3. 流程优化建议建立 RocketMQ、Kafka 等消息中间件客户端的日志级别基线规范将本次增强的清理脚本推广到其它 K8s 节点排查类问题形成标准化 playbook，缩短定位时间参考资料RocketMQ Client 日志级别配置说明Docker 存储驱动 overlay2 工作原理Linux drop_caches 与内存回收
next-socks5：基于 Rust 的轻量级 SOCKS5 服务器实战指南一、概述1. 简介A. 是什么next-socks5 是一个用 Rust 编写的轻量级、可扩展的 SOCKS5 服务器，完整实现了 RFC 1928 与 RFC 1929 协议规范。项目由 ZingerLittleBee 开源维护，采用纯 Rust 编写，无任何 C 依赖，可生成完全静态的 musl 二进制文件以及基于 scratch 的约 3.5 MB 容器镜像。项目核心特点：自研协议栈：手写 SOCKS5 协议解析，依赖足迹刻意保持精简双模式运行：TUI 终端仪表盘与适合容器的 headless 模式安全默认：默认开启出口流量过滤，防止 SSRF 与开放中继多种部署：支持一键脚本、Docker、预编译二进制、源码编译四种方式B. 为什么学传统 SOCKS5 实现（如 Dante、3proxy）存在以下痛点：老牌服务器多为 C 语言实现，依赖复杂，编译环境要求高缺乏现代运维所需的可观测性工具UDP 中继在 NAT 与容器环境下配置繁琐安全默认不足，容易因配置疏忽变成开放中继next-socks5 通过 Rust 的内存安全特性、TUI 仪表盘的实时观测能力、以及为 NAT/Docker 场景设计的 UDP 配置选项，系统性地解决了这些问题。C. 学完能做什么在自建服务器或云主机上快速部署一个安全的 SOCKS5 代理使用 TUI 仪表盘实时观测吞吐、连接数与错误统计在 NAT、Docker bridge 等复杂网络环境下正确配置 UDP 中继根据 RFC 1928 规范理解 SOCKS5 协议的工作原理2. 前置知识A. 必备技能基本的 Linux 命令行操作能力了解 TCP/UDP 协议基础熟悉代理服务器的基本概念B. 推荐知识Rust 编程基础（仅在源码编译时需要）Docker 与 docker compose 的使用防火墙配置（iptables、ufw 或 nftables）二、核心特性1. 协议支持A. SOCKS5 命令next-socks5 支持 RFC 1928 定义的核心命令：命令支持情况说明CONNECT完整支持用于 TCP 流量代理，如 HTTP、HTTPSUDP ASSOCIATE完整支持用于 UDP 流量代理，如 DNS、QUICBIND设计拒绝按设计返回回复码 0x07，出于安全考虑不开放B. 认证机制支持两种认证方式：No-Auth（0x00）：无认证，适用于受信任网络Username/Password（0x02）：用户名密码认证，符合 RFC 1929 规范认证模式下可配置多组凭证：客户端只要匹配列表中任意一组用户名密码即可通过，无需为每个用户开放独立端口。C. 地址类型支持三种 ATYP（Address Type）：0x01：IPv4 地址0x04：IPv6 地址0x03：Domain 域名（服务器端执行 DNS 解析）无论是 CONNECT 还是 UDP ASSOCIATE 目标，服务器都会执行 DNS 解析，避免客户端泄露真实 DNS 请求。D. RFC 错误码映射完整覆盖 RFC 1928 定义的回复码 0x00 至 0x08，典型映射关系：场景回复码含义成功0x00succeeded连接数超限0x02connection not allowed by ruleset网络不可达0x03network unreachable主机不可达0x04host unreachable连接被拒0x05connection refusedTTL 过期0x06TTL expired不支持的命令0x07command not supported不支持的地址类型0x08address type not supported2. 安全设计A. 出口过滤默认开启服务器默认拒绝转发到以下地址段，作为 SSRF 与开放中继的防护：回环地址（127.0.0.0/8、::1）链路本地地址（169.254.0.0/16），包括云元数据地址 169.254.169.254私有地址段（RFC 1918：10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）如确实需要访问内部目标，可通过配置文件中的 egress 段放宽限制。B. 防 slowloris 攻击握手阶段（greeting + auth + request）设置了独立的超时时间（默认 10 秒），超过 handshake_ms 未完成握手的连接将被强制断开，防止慢速攻击占用连接资源。C. 连接数限制提供两个可选的并发上限配置：max_connections：全局并发上限，防止文件描述符耗尽max_per_ip：单 IP 并发上限，防止单客户端独占资源或暴力破解两个限制默认不启用，需要根据实际场景显式配置。3. 性能与体量A. 性能表现在单台 4 核云主机（loopback 测试）上：中继吞吐：约 2 GB/s单请求附加延迟：约 1.6 ms新建连接速率：约 6000 次/秒profiling 结果显示代理本身受限于内核网络栈，不存在锁竞争，proxy 不是性能瓶颈。B. 体量小巧静态 musl 二进制：约 3.5 MB 容器镜像（scratch 基础镜像）无 C 依赖：纯 Rust 实现，便于跨平台分发Headless 构建：可移除 ratatui 与 crossterm 依赖，进一步减小体积graph LR A[客户端] -->|SOCKS5 协议| B[next-socks5 服务器] B -->|出口过滤检查| C{是否允许?} C -->|允许| D[目标服务器] C -->|拒绝| E[返回错误] D -->|响应数据| B B -->|代理响应| A subgraph 服务器内部 F[协议解析] --> G[认证校验] G --> H[命令处理] H --> I[CONNECT 中继] H --> J[UDP ASSOCIATE 中继] end三、安装方式1. 一键脚本（推荐）A. 基础用法一键脚本会自动选择 binary 或 docker 方式，生成凭证与空闲端口，并启动服务：# 默认安装：binary 方式，开启认证，自动生成用户名密码与端口 curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh | shB. 常用参数通过 -s -- 将参数传递给 install.sh：# 指定端口 curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --port 1080 # 使用 Docker 方式（host 网络，UDP ASSOCIATE 可用） curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --method docker # 显式指定凭证 curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --method docker --auth --user alice --pass secret --port 1080 # 仅监听本地 curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --no-auth --listen 127.0.0.1 --port 1080C. 完整参数表参数说明默认值--method <binary\docker>安装方式binary--auth / --no-auth是否启用认证--auth--user / --pass认证凭证随机生成--port 监听端口随机空闲端口--listen 绑定地址0.0.0.0--udp-port-range UDP 中继端口范围操作系统临时端口--udp-advertise UDP 通告 IP（NAT 后）绑定的本地 IP--version 指定版本latest--bin-dir 二进制安装目录（binary 方式）/usr/local/bin--dir compose 部署目录（docker 方式）./next-socks5-deploy--no-service仅安装不启动服务关闭D. 平台与初始化系统支持binary 安装目标为 Linux（musl x86_64/aarch64），会自动配置 systemd 或 OpenRC 服务。若系统两者均不存在，二进制与配置文件仍会被安装，但不会自动启动，需要手动启动或选择 docker 方式。脚本仅依赖 POSIX sh，无需 bash。2. Docker 部署A. 通过安装脚本生成 Compose最简单的方式：让安装脚本自动生成 docker-compose.yml 与 config.toml 并启动容器：curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/next-socks5/main/install.sh \ | sh -s -- --method docker --auth --port 1080文件生成在 ./next-socks5-deploy/ 目录，可通过 --dir 覆盖，随后执行 docker compose up -d。B. 手动 docker run无认证模式，使用 host 网络以保证 UDP ASSOCIATE 可用：docker run -d --name next-socks5 --network host \ ghcr.io/zingerlittlebee/next-socks5:latest --listen 0.0.0.0:1080使用配置文件（启用认证）：docker run -d --name next-socks5 --network host \ -v "$PWD/config.toml:/etc/next-socks5/config.toml:ro" \ ghcr.io/zingerlittlebee/next-socks5:latest --config /etc/next-socks5/config.tomlC. docker-compose 编排services: next-socks5: image: ghcr.io/zingerlittlebee/next-socks5:latest container_name: next-socks5 restart: unless-stopped network_mode: host volumes: - ./config.toml:/etc/next-socks5/config.toml:ro tmpfs: - /run/next-socks5 command: ["--config", "/etc/next-socks5/config.toml"]启动服务：docker compose up -d镜像支持多架构（linux/amd64、linux/arm64），同时打有版本号（如 0.1.0）与 latest 标签。容器始终以 headless 模式运行。D. tmpfs 与 admin socket容器以非特权用户（uid 65534）运行，需要可写的 /run/next-socks5 目录用于 admin socket。若不挂载 tmpfs，attach 命令将无法连接，服务日志会出现 admin endpoint disabled: Permission denied。3. 预编译二进制从 Releases 页面下载静态 musl 构建版本：curl -fL -o next-socks5.tar.gz \ https://github.com/ZingerLittleBee/next-socks5/releases/latest/download/next-socks5-x86_64-unknown-linux-musl.tar.gz tar xzf next-socks5.tar.gz ./next-socks5-x86_64-unknown-linux-musl/next-socks5 serve --no-tui --listen 0.0.0.0:1080ARM64 架构将 x86_64 替换为 aarch64 即可。4. 源码编译需要较新版本的 Rust 稳定工具链：git clone https://github.com/ZingerLittleBee/next-socks5 cd next-socks5 cargo build --release ./target/release/next-socks5 serve # 启用 TUI ./target/release/next-socks5 serve --no-tui # headless 模式 # 仅编译 headless 版本（移除 TUI 依赖） cargo build --release --no-default-features也可直接从 git 安装：cargo install --git https://github.com/ZingerLittleBee/next-socks5四、配置说明1. 配置文件结构配置采用 TOML 格式（参考仓库中的 config.example.toml），CLI 参数会覆盖配置文件中的同名项。listen = "0.0.0.0:1080" [auth] method = "password" # "none" 或 "password" auth.users username = "alice" password = "secret" auth.users username = "bob" password = "hunter2" [timeouts] handshake_ms = 10000 connect_ms = 10000 tcp_idle_ms = 300000 udp_idle_ms = 60000 [limits] max_connections = 2048 max_per_ip = 64 [admin] enabled = true # socket = "/run/next-socks5/admin.sock"2. 认证配置A. 多用户支持method = "password" 时，每个凭证配置一个 auth.users 段，客户端匹配任意一组凭证即通过认证（RFC 1929）。这是在同一端口服务多个用户的标准做法，无需为每个用户开放独立端口。B. 开放代理method = "none" 时为开放代理，users 列表将被忽略。仅在受信任网络中部署时使用此模式，仪表盘仍会记录每次认证尝试。3. 超时与连接限制A. 超时配置配置项说明默认值handshake_ms握手阶段总时限（防 slowloris）10000connect_ms连接目标服务器超时10000tcp_idle_msTCP 连接空闲回收时间300000udp_idle_msUDP 关联空闲回收时间60000B. 连接数限制两个限制项均为可选，默认不设上限：max_connections：全局并发上限，作为文件描述符/任务耗尽的兜底max_per_ip：单 IP 并发上限，防止单一客户端独占或暴力破解每条 CONNECT 中继占用约 2 个文件描述符，配置时需参考操作系统的 RLIMIT_NOFILE 上限。公网部署场景建议同时配置两项。C. 公网部署建议next-socks5 内置无认证速率限制，公网暴露时建议：同时设置 max_connections 与 max_per_ip在监听端口前部署主机防火墙或 fail2ban保持默认的出口过滤开启4. UDP 中继配置A. UDP 在 NAT 与 Docker 中的挑战CONNECT 仅使用单个 TCP 监听端口即可工作，但 UDP ASSOCIATE 需要独立的 UDP 中继 socket。默认情况下每个关联绑定一个操作系统分配的临时端口，服务器通告客户端必须发送数据报到的 BND.ADDR:BND.PORT（RFC 1928）。通过 [udp] 段两个选项可让 UDP 在防火墙与 NAT 后正确工作：[udp] port_range = "40000-40100" advertise = "203.0.113.42"B. port_range（端口范围）将每个关联的 UDP socket 绑定到指定范围内，而非随机临时端口，这样防火墙/NAT 只需开放该范围。每个关联独占一个 socket，范围大小应大于等于预期并发 UDP 客户端数"40000-40000" 表示单端口，UDP 将串行处理范围耗尽时，新的 UDP ASSOCIATE 返回 general failureC. advertise（通告地址）填入 UDP ASSOCIATE 回复中的 IP 地址。默认情况下服务器通告客户端 TCP 连接到达的服务器侧 IP（控制 socket 的本地地址）。当该 IP 客户端不可达时（NAT 后或 Docker bridge 网络），需要覆盖通告端口始终是真实绑定的端口，因此 NAT/转发必须是端口保留（1:1）通告地址不可达是 TCP 通但 UDP 不通的首要原因接受裸 IP 或 ip:port 格式（端口被忽略），格式错误会在启动时拒绝5. Docker 网络配置A. host 网络（推荐）提供的 compose 使用 network_mode: host（Linux），无需端口映射：network_mode: hostB. bridge 网络发布 TCP 控制端口与 UDP 范围时必须使用短语法（compose 长语法不支持范围），并设置 advertise 为宿主机公网 IP：ports: - "1080:1080/tcp" - "40000-40100:40000-40100/udp"C. 防火墙规则需要开放控制端口 1080/tcp 与 UDP 范围 40000-40100/udp：# ufw ufw allow 1080/tcp && ufw allow 40000:40100/udp # nftables nft add rule inet filter input udp dport 40000-40100 accept # iptables iptables -A INPUT -p udp --dport 40000:40100 -j ACCEPTD. 端口重映射 NAT 的限制端口重映射（PAT/对称）NAT 无法与多端口范围协同工作（转换后通告的内部端口不正确）。可选方案：使用单固定端口（"40000-40000"）配合 1:1 转发或直接部署在可达公网 IP 上五、使用方法1. 命令行接口next-socks5 提供三个子命令：next-socks5 打印帮助（裸调用永不启动服务器） next-socks5 serve [OPTIONS] 运行服务器（别名 run） next-socks5 attach [OPTIONS] 附加到运行中的服务器仪表盘A. 服务器选项参数说明--config TOML 配置文件路径--listen 覆盖监听地址（如 0.0.0.0:1080）--no-tuiheadless 模式（事件输出到 stdout）--no-admin禁用本地 admin/attach 端点--admin-socket 覆盖 admin socket 路径-h, --help打印帮助B. attach 选项参数说明--socket 连接的 admin socket（默认 /run/next-socks5/admin.sock）2. 启动服务A. TUI 模式（默认）不带 --no-tui 直接运行服务器即可启动仪表盘：next-socks5 serve --listen 127.0.0.1:1080B. headless 模式适用于 systemd 与容器场景，事件流输出到 stdout：next-socks5 serve --no-tui --listen 0.0.0.0:10803. TUI 仪表盘仪表盘默认开启，展示以下信息：实时吞吐（含 30 秒趋势图）成功/错误统计可排序的活跃连接表滚动日志面板A. 键位映射按键功能Tab在连接表与日志面板间切换焦点（聚焦面板会高亮）s循环切换排序键：ID、UP↓、DOWN↓、AGE↓（显示在表标题中）↑/↓ 或 k/j焦点面板单行滚动PgUp/PgDn焦点面板整屏滚动q / Ctrl-C退出B. 模拟数据预览为便于演示或测试仪表盘功能，可使用 --mock 参数注入合成数据流：# 本地预览 cargo run --release -- serve --listen 127.0.0.1:1080 --mock # 已安装二进制 next-socks5 serve --listen 127.0.0.1:1080 --mock--mock 仅供演示与测试，生产环境切勿启用。4. Attach 已运行服务通过 systemd/OpenRC/Docker 安装的服务以 headless 模式运行，但仍通过本地 Unix socket（默认 /run/next-socks5/admin.sock）提供实时仪表盘。在同一台机器上即可附加观察，无需重启，也无需额外开关。A. 基本用法# 1. SSH 到服务所在主机（默认 socket 需要 root） ssh root@your-server # 2. Attach 到默认 socket next-socks5 attach # Docker：在容器内执行 docker exec -it next-socks5 next-socks5 attachB. 自定义 socket 路径next-socks5 attach --socket /tmp/ns5.sockC. 安全特性仅本地访问，无网络暴露无认证机制（依赖本地权限）只读：attach 客户端只能观察，不能控制服务器按 q 可分离；服务器停止时仪表盘会显示 connection lost 后退出。D. 手动安装场景--no-service 手动安装时，进程以当前用户运行，默认 /run 路径通常不可写。需指定可写的 socket 路径：next-socks5 serve --no-tui --admin-socket /tmp/ns5.sock next-socks5 attach --socket /tmp/ns5.sock六、工作原理1. SOCKS5 协议基础SOCKS5 协议定义于 RFC 1928，工作流程分为三个阶段：flowchart TD A[阶段一：协商] --> B[阶段二：认证] B --> C[阶段三：请求处理] C --> D{命令类型} D -->|CONNECT| E[TCP 中继] D -->|UDP ASSOCIATE| F[UDP 中继] D -->|BIND| G[拒绝 0x07] E --> H[双向数据转发] F --> H2. CONNECT 流程详解sequenceDiagram participant U as 用户 participant C as next-socks5 客户端 participant S as next-socks5 服务器 participant T as 目标服务器 U->>C: curl --socks5 C->>S: TCP 握手 greeting S-->>C: 选择认证方式 C->>S: 凭证 RFC 1929 S-->>C: 认证成功 C->>S: CONNECT 请求 ATYP + DST.ADDR + DST.PORT S->>S: 出口过滤检查 S->>T: 建立连接 T-->>S: 连接建立 S-->>C: 回复 0x00 成功 C->>T: 双向中继数据A. 协商阶段客户端连接服务器后发送 greeting 消息，包含客户端支持的认证方式列表。服务器从中选择一种，返回所选方式。B. 认证阶段若服务器选择用户名/密码认证（0x02），客户端发送 RFC 1929 定义的凭证，服务器校验后返回成功或失败。C. 请求阶段认证通过后，客户端发送请求，包含命令类型、目标地址类型与目标地址。服务器根据命令执行相应操作。2. UDP ASSOCIATE 实现细节A. UDP 封装格式UDP ASSOCIATE 使用独立的 UDP socket 转发数据，每个数据报需按 RFC 1928 封装：字段含义RSV保留字段（2 字节，0x0000）FRAG分片标志（next-socks5 丢弃 FRAG != 0 的分片）ATYP目标地址类型DST.ADDR目标地址DST.PORT目标端口DATA实际数据报内容B. 安全约束next-socks5 在 UDP 中继中实施以下安全策略：丢弃 FRAG != 0 的分片，避免重组攻击源 IP 过滤：仅接受来自控制连接客户端 IP 的数据报BND.ADDR 永不为 0.0.0.0，确保客户端有可达地址空闲回收：超过 udp_idle_ms 无活动的关联自动清理3. 出口过滤机制默认出口过滤作为 SSRF 防护层，覆盖以下范围：flowchart LR A[目标地址] --> B{出口过滤检查} B -->|回环地址| C[拒绝] B -->|链路本地| C B -->|私有地址段| C B -->|公网地址| D[允许转发] D --> E[建立连接] C --> F[返回错误]七、最佳实践1. 公网部署公网部署场景建议遵循以下原则：始终启用用户名密码认证，避免开放代理同时配置 max_connections 与 max_per_ip，防止资源耗尽保持默认出口过滤开启，防止 SSRF 攻击在监听端口前部署防火墙或 fail2ban，弥补认证速率限制的缺失选择复杂凭证，密码至少 20 字符2. NAT 与 Docker 环境UDP 在 NAT/容器环境中需特别注意：优先使用 host 网络模式，避免端口映射问题bridge 模式下使用短语法发布端口范围advertise 地址必须为客户端可达的公网 IP范围大小应覆盖预期并发 UDP 客户端端口重映射 NAT 场景使用单固定端口配合 1:1 转发3. 容器化部署Docker 部署的最佳实践：始终挂载 tmpfs /run/next-socks5，确保 admin socket 可用配置文件以只读方式挂载设置 restart: unless-stopped 实现自重启使用版本标签而非 latest，便于版本追踪4. 监控与观测利用内置 TUI 仪表盘进行实时观测：通过吞吐趋势图发现流量异常通过错误统计发现认证失败激增通过活跃连接表识别可疑连接对生产环境使用 attach 远程观察，不影响服务参考资料next-socks5 GitHub 仓库RFC 1928: SOCKS Protocol Version 5RFC 1929: Username/Password Authentication for SOCKS V5next-socks5 性能测试文档next-socks5 配置示例
服务器集群运维文档一、集群概览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：在服务中执行命令参考资料