问题现象

在 macOS 上 SSH 登录一台 Ubuntu 服务器,连接永久卡死。ssh -v 的调试输出停在:

1
2

debug1: Authentications that can continue: publickey
debug1: Next authentication method: publickey

之后再无任何输出,进程既不报错也不超时,就这样一直挂着。

更诡异的是:

• ssh-add -l 同样卡死
• 重启电脑后问题依旧
• 换用系统自带的 /usr/bin/ssh(9.x)和 Homebrew 的 OpenSSH 10.2 都卡

排查思路:逐层缩小范围

第一层:定位卡死的环节

-v 日志停在 Next authentication method: publickey,下一步本应是 Offering public key ...。在这两步之间,ssh 客户端会做一件事:向 ssh-agent 查询可用密钥。agent 不响应,客户端就无限等待。

初步怀疑 agent。检查环境变量:

1
2

$ echo $SSH_AUTH_SOCK
/var/run/com.apple.launchd.b6Kz3tJtrK/Listeners

这是 macOS 系统 launchd 管理的标准 agent socket,路径本身正常。

第二层:绕过 agent 做对照实验

关键的分流测试——让 ssh 完全不碰 agent:

1

ssh -o IdentityAgent=none -o IdentitiesOnly=yes -i ~/.ssh/id_rsa root@<server>

立即成功登录。 这一步把问题 100% 锁定在 ssh-agent 环节:服务器没问题、网络没问题、密钥没问题,就是 agent 死了。

小插曲:先用 id_ed25519 测试时返回 Permission denied (publickey)——虽然被拒,但”立即返回”本身就是有效信息(说明绕过 agent 后流程通畅),换成服务器上实际授权的 id_rsa 即成功。

第三层:审问 launchd

macOS 上系统 ssh-agent 是 socket 激活式的:launchd 监听 socket,有连接进来才拉起 /usr/bin/ssh-agent -l。查看服务状态:

1
2
3
4
5
6

$ launchctl print gui/$(id -u)/com.openssh.ssh-agent
...
state = spawn scheduled
runs = 61
last exit code = 255
...

铁证:runs = 61,last exit code = 255。 launchd 一直在拉起 agent,但它每次启动后立即以 255 退出,已经反复崩了 61 次。客户端卡死的机制也清晰了:

1. ssh / ssh-add 连接 socket
2. launchd 收下连接,拉起 agent
3. agent 秒退,连接悬空
4. 客户端永远等不到响应
5. launchd 有 10 秒的重启节流,于是日志里每 10 秒一次”Successfully spawned → service inactive”的循环

用统一日志确认了这个循环:

1

log show --last 2m --predicate 'process == "ssh-agent" OR eventMessage CONTAINS "ssh-agent"' --info --debug

每次生命周期只有 5 毫秒:spawn → 查询用户信息(getpwuid)→ 退出。没有留下任何错误日志——launchd 模式下 stderr 被丢弃了。

第四层:让它当面崩给我看

既然 launchd 模式下看不到报错,那就手动跑,把 stderr 抓出来:

1
2
3
4
5
6

$ /usr/bin/ssh-agent; echo "exit: $?"
agent_cleanup_stale: stat "/Users/cat/.ssh/agent/.": Permission denied
agent_cleanup_stale: stat "/Users/cat/.ssh/agent/..": Permission denied
unix_listener_tmp: bind "/Users/cat/.ssh/agent/s.xxxx.agent.xxxx": Permission denied
main: Couldn't prepare agent socket
exit: 255

真相大白。 新版 ssh-agent 会在 ~/.ssh/agent/ 目录下创建 socket,而这个目录的权限坏了,导致 bind 失败,fatal() 退出 255。

根因:一个缺失的 x 位

看权限:

1
2

$ ls -ld ~/.ssh/agent
drw-------@ 3 cat  staff  96  4月  4 10:37 /Users/cat/.ssh/agent

属主没问题,坏在权限位:drw-------——目录缺了 execute(x)位。

对目录而言,x 是”进入/穿越”权限。没有它:

• 可以 ls 列出文件名(靠 r 位)
• 但无法 stat 目录内任何文件
• 无法在目录内创建新文件(socket 的 bind 也就必然失败)

这种坏法的典型成因:某次对 ~/.ssh 递归执行了 chmod 600。600 对私钥文件是正确的,但对目录是致命的——目录必须有 x 才能正常使用。

这也完美解释了所有诡异现象:

修复:一条命令

1

chmod 700 ~/.ssh/agent

验证:

1
2
3

$ ssh-add -l          # 立即返回,agent 复活
$ ssh-add ~/.ssh/id_rsa ~/.ssh/id_ed25519
$ ssh root@<server>   # 秒进

经验总结

1. “卡死”和”报错”是两种线索。 卡死意味着某一方在无限等待,顺着协议流程找”下一步本应发生什么”,就能定位是在等谁。

2. 对照实验是最快的手术刀。 -o IdentityAgent=none 一条命令就把嫌疑范围从”客户端/网络/服务器/agent”缩到只剩 agent。

3. socket 激活服务的报错会被吞掉。 launchd 拉起的进程 stderr 默认丢弃,launchctl print 里的 runs 和 last exit code 是最重要的健康指标;拿不到日志时,手动在终端复现启动是终极手段。

4. chmod 600 不要递归用在目录上。 ~/.ssh 的标准权限:目录 700,私钥 600,公钥/config/known_hosts 644 或 600。修权限时用 chmod 700 目录 + chmod 600 私钥 分开处理,或者:

   1 2	find ~/.ssh -type d -exec chmod 700 {} \; find ~/.ssh -type f -name 'id_*' ! -name '*.pub' -exec chmod 600 {} \;

5. exit code 255 在 OpenSSH 语境里就是 fatal()。 看到它,去找初始化阶段的失败点(socket、权限、配置解析),而不是运行时逻辑。

一个丢失的 x 位,让 ssh-agent 无声地崩溃了 61 次,拖着两个版本的 ssh 客户端一起陪葬,还扛过了一次重启。定位它花了四层排查,修复它只要九个字符。

很多工具都是之前已经实现的零碎任务,这次结合核心诉求,把下面的问题整合起来：

• 两个平台的 API 风格完全不同，一个 OAuth2 PKCE，一个 clientId + clientSecret
• 文件需要在两边做匹配，靠的是 SHA1 而不是文件名
• 想做增量同步，就得维护一份文件索引
• 生成媒体库的 strm 文件，还要写入远程 NAS
• 最后需要一个下载服务，能把 123 的直链能力用起来

一个个手动操作太累了，于是有了 CloudPanBridge。

架构总览

整个项目分为三层：

1
2
3
4
5
6
7
8
9
10
11
12

┌─────────────────────────────────────────────┐
│              CLI 命令行工具                    │
│  export  dedup  match  sync  strm  serve     │
├─────────────────────────────────────────────┤
│          CloudPan SDK (统一封装)               │
│    ┌──────────────┐  ┌──────────────┐        │
│    │  115 Client  │  │  123 Client  │        │
│    └──────────────┘  └──────────────┘        │
├─────────────────────────────────────────────┤
│         Database (SQLite / MySQL)            │
│         HTTP Service (FastAPI)               │
└─────────────────────────────────────────────┘

最底层是 SDK 层，分别封装了两个平台的完整开放 API；中间是 CLI 工具层，把业务逻辑编排成一个个命令；上层是 运维层，靠一个 shell 脚本编排定时任务。

数据库是整个系统的核心枢纽，所有信息流经它串联——文件索引、云盘匹配关系、同步任务状态，全部落库管理。

核心工作流

整个自动化管线按照 1→2→3→4→5 的顺序执行：

1. 文件导出

把云盘上的文件列表完整拉到数据库，这是后续一切操作的基础。

115 的导出做了三阶段设计：先分页拉取文件列表（不拉目录信息），再批量调用目录信息 API 构建路径，最后回填数据库。增量模式下，拉到比上次更新时间更旧的文件就自动停止，效率很高。

123 的导出用了 UPSERT 批量写入（5000 条一批），支持并发扫描子目录，还有指数退避的限流保护。回收站里的文件自动跳过。

这部分在代码里是最复杂的——要处理分页、限流、断点续传、增量同步、多用户隔离。

2. 重复文件检测

同一目录下，通过文件大小 + SHA1（或 MD5、ETag）判断重复。特别针对网盘场景做了 --detect-suffix 支持——匹配文件名末尾的 (1) 或 （1） 这类后缀，配合 --delete 可以安全批量清理。

3. 跨云盘匹配

匹配逻辑没有在 Python 里做循环，而是直接生成 SQL，在数据库服务端完成 JOIN：

1
2
3
4
5

SELECT f115.*, f123.*
FROM files f115
INNER JOIN files f123
    ON f123.size = f115.size
   AND SUBSTR(f123.full_path, offset) = SUBSTR(f115.full_path, offset)

匹配结果通过临时表 + 单条 UPDATE 批量写入，100 万级数据分分钟搞定(1C1G的垃圾服务器)。全程数据库服务端计算，Python 只收结果，内存零压力。

4. 生成 strm 文件

为媒体播放器生成 .strm 文件（本质是一个指向 HTTP URL 的文本文件），内容形如：

1

http://172.16.16.170:8808/sha1/{sha1}/size/{size}/{encoded_name}

支持两种模式：本地写入和远程 SFTP 写入。我用的是 --ssh-password 参数直接写入 NAS 上的目录。47 万个文件，8 线程并行写入，大约 8 分钟跑完。

5. 同步与下载服务

同步（115 → 123） 基于 123 云盘的 SHA1 秒传接口，文件不需要下载再上传，服务端直接复制。大文件优先处理，已匹配的文件自动跳过。并发数通过 -c 参数控制。

下载服务 基于 FastAPI + uvicorn 构建，支持两种模式：

• 302 重定向模式：查询直链后 302 跳转，服务端不接触文件数据
• 代理缓存模式（--proxy）：文件边下边转，支持 HTTP Range 断点续传，缓存到本地磁盘

代理模式做了一些有意思的优化：

1
2
3
4
5

# 多线程分段下载：123 的文件用 2 个线程同时拉
# os.pwrite 按偏移量原子写入，线程安全
# LRU 缓存按 mtime 淘汰，默认 50GB 上限
# 403 自动重试：自动换 URL 再试
# 多 reader 保护：最后一个消费者断开才清理缓存

最妙的是 SHA1 秒传兜底机制——所有常规下载路径都失败时，自动触发 123 的 SHA1 秒传接口完成兜底，并更新数据库关联供后续复用。

技术亮点

双数据库后端的优雅抽象

项目同时支持 SQLite 和 MySQL，但不是用 ORM，而是自己做了抽象层：

1
2
3

DatabaseBackend (抽象基类)
├── SQLiteBackend  — UPSERT: ON CONFLICT
└── MySQLBackend   — UPSERT: ON DUPLICATE KEY

环境变量一键切换：

1
2

export CLOUDPAN_DB_TYPE=mysql
export CLOUDPAN_DB_HOST=...

Mark-and-Sweep 增量清理

每次导出生成唯一的 sync_id，写入每条记录时标记 last_sync_id = sync_id。导出完成后，清理该云盘下 last_sync_id != sync_id 的记录——这就是云盘上已被删除的文件。增量模式下不执行清理，防止误删。

授权管理

115 用的是 PKCE 扫码授权（比传统授权码模式更安全），Token 刷新后旧的立即作废。123 则是 clientId + clientSecret 直接获取 access_token，30 天有效期。缓存统一存放在 ~/.cloudpan/auth_cache.json。

生产部署

日常运维通过一个 shell 脚本编排：

1
2
3
4
5
6
7
8

# 每 4 小时：导出 → 去重 → 匹配 → 生成 strm
0 */4 * * * /path/to/cloudpan-ops.sh every-4h

# 每天凌晨 3 点：同步文件
0 3 * * * /path/to/cloudpan-ops.sh daily

# 下载服务常驻运行
./cloudpan-ops.sh serve

脚本加了日志、PID 管理、命令可用性检测，放在 crontab 里基本不用管。

项目结构

1
2
3
4
5
6
7
8

CloudPanBridge/
├── src/cloudpan_sdk/
│   ├── base/              # 抽象基类、异常、数据模型
│   ├── platform_115/      # 115 API 实现
│   ├── platform_123/      # 123 API 实现
│   ├── cli/               # CLI 工具和业务逻辑
│   └── server/            # FastAPI 下载服务
└──cloudpan-ops.sh        # 运维编排脚本

platform_115 和 platform_123 是纯粹的 SDK 封装，cli/ 目录才是真正的业务逻辑所在。这种分层让 SDK 可以独立复用——即使不用这套自动化管线，单纯想调 115 或 123 的 API，也可以直接 pip install 后 import 使用。

写在最后

这个项目不是一个大而全的框架，而是一组解决具体问题的工具集合。每个命令单独拿出来都能用，组合起来就形成了一条完整的自动化管线。

如果你也有类似的场景——管理多个云盘、做媒体库自动化、或者单纯想研究网盘 API 的封装方式，希望对你有参考价值。

在上一篇博文中，我们展示了双 3090/四 3090 环境下部署 Qwen3-30B 的基础性能。今天，通过引入 OLLAMA_KV_CACHE_TYPE=q8_0，我们将这项测试推向了新的巅峰：在不损失响应速度的前提下，显存占用降低了 **24%**。

1. 核心调优：什么是 KV Cache 量化？

大模型在处理长文本时，会把历史对话的 key 和 value 存在显存里（即 KV Cache）。对于 128k 这种超长上下文，这部分内存占用往往比模型本身还要大。
通过设置环境变量：

1
2

export OLLAMA_KV_CACHE_TYPE=q8_0

我们将 KV Cache 从 16 位压缩到 8 位。结果令人震惊。

2. 优化前后数据全量对比

基于 4x 3090 (96GB VRAM) 环境，模型为 Qwen3-Coder-30B-A3B-Instruct-Q8：

显存占用对照表

推理性能对照表 (4 并发)

3. 技术分析：为什么必开 Q8 Cache？

1. 带宽解耦：在 128k 场景下，计算不再是瓶颈，显存数据的搬运速度才是。Q8 减少了搬运量，让 A3B 推理引擎跑得更欢。
2. 容错空间：在 128k 仅需 66GB 的情况下，你的系统不仅能稳定运行 AI 编程插件（Trae/Cursor），还能同时开启 4K 显示器渲染、多浏览器窗口，甚至后端本地调试环境，而完全不必担心显存溢出导致的系统卡死。

4. 总结：生产力环境的最佳实践

如果你拥有 48GB 以上的显存，部署 Qwen3-30B 时的黄金法则：

• 锁死 128k 上下文：给 AI 最完整的项目记忆。
• 强制开启 q8_0 Cache：用极微小的精度损失换取巨大的显存余量和更稳的 TPS。
• 并发数设为 4-8：充分利用 3090 集群的多卡并行能力。

在本地部署大模型的道路上，显存容量决定了“深度”，而架构设计决定了“速度”。最近我将本地环境升级到了 4x RTX 3090 (96GB VRAM)，并部署了 Qwen3-Coder-30B-A3B-Instruct-Q8。以下是针对 32k 到 128k 上下文的真实性能压测报告。

1. 模型架构：A3B 的魔力

Qwen3-Coder-30B 采用了 Mixture of Experts (MoE) 架构。虽然它有 30B 的总参数量确保了逻辑深度，但推理时仅激活 3B 参数。这使得它在处理大规模代码理解时，响应速度甚至超越了许多 14B 的稠密模型。

2. 内存与性能矩阵

通过（4 并发）实测，数据如下：

3. 关键洞察：128k 为什么不掉速？

传统的 Dense（稠密）模型在上下文增加时，计算压力会显著增大。但在本次 128k 压测中，TPS 仅从 141 跌落至 132，损耗极小。

1. 显存完全覆盖：87GB 的占用完美落在 96GB 的物理上限内，避免了任何系统交换（Swap）导致的卡顿。
2. KV Cache 效率：Q8 量化下的 KV Cache 虽然巨大（约 56GB），但由于 4 卡并行带宽极高，注意力机制的计算开销被有效摊平。
3. 冷启动 vs 热启动：实测显示冷启动（加载模型）需要约 45 秒，但一旦热身完成，TTFT 稳定在 0.4s 级别。

4. 最终配置建议 (4x 3090 用户)

如果你的显存超过 80GB，不要犹豫，直接锁死 128k：

1
2
3
4
5
6
7
8

# 环境变量
export OLLAMA_NUM_PARALLEL=4
export OLLAMA_FLASH_ATTENTION=1

# Modelfile 核心参数
PARAMETER num_ctx 131072
PARAMETER temperature 0.1

128k 带来的“长效记忆”是编程 AI 的终极杀手锏。在本地算力的支撑下，我们终于告别了云端模型的 Token 焦虑。

1. 硬件与模型选型：为什么是 Qwen3-30B？

对于有充足显存的配置，Qwen3-Coder-30B 是目前相对较优的“版本答案”：

• MoE 架构：总参数 30B，推理时仅激活约 3.3B。这意味着它拥有大模型的“深度”，却具备小模型的“速度”。
• 长上下文支持：原生支持 128k 上下文，适合 Repo-level 的代码理解。

2. 核心部署配置

2.1 环境变量调优 (Server-Side)

为了压榨并发性能，我们在启动 Ollama 前设置了如下关键参数：

1
2
3
4
5

# 启用 Flash Attention 减少长文本压力
export OLLAMA_FLASH_ATTENTION=1
# 模型驻留显存，消除冷启动等待
export OLLAMA_KEEP_ALIVE=12h

2.2 自定义 Modelfile

我们创建了 my-code-qwen3 模型，固定了黄金生产力参数：

1
2
3
4
5

FROM qwen3-coder:30b-instruct-q8_0
PARAMETER num_ctx 65536
PARAMETER temperature 0.1
PARAMETER repeat_penalty 1.15

3. 性能压测实录 (Benchmark)

在并发数 $N=4$ 的高频压力测试下，不同上下文长度的表现如下：

数据解读：

• 0.4s 的 TTFT：意味着在你按下快捷键的瞬间，代码已经开始流式输出。
• 120+ TPS 的总输出：证明了 MoE 架构在 3090 上的巨大带宽优势，足以支撑多人或多任务同时运行。
• 64k 甜点位：测试显示 64k 下性能不降反升，说明该尺寸最契合目前的算力调度。

4. 总结

双 3090 配合 Qwen3-Coder-30B MoE 模型，为单人开发者提供了一个“低延迟、高智力、大容量”的完美私有大脑。

• 如果你追求极致速度：32k 上下文 + Q4 量化。
• 如果你追求生产力平衡：64k 上下文 + Q8 量化（推荐）。
• 如果你需要处理庞大工程：128k 上下文 + KV Cache 量化。

写在最后：本地 AI 的魅力在于，它不只是一件工具，更是你算力的延伸。如果你需要大量的token消耗,除了大厂的Coding Plan,本地也许是个不错的选择。

本文结合实战经验，深度分析三类核心部署脚本的设计逻辑，助你构建稳健的私有网络。

一、 服务端：自动化网关的基石

服务端的职责不仅仅是握手，更重要的是充当流量转发的中转站。

1. 核心自动化逻辑

• 网络环境初始化：自动开启内核级别的 net.ipv4.ip_forward 转发功能，确保虚拟网卡与物理网卡之间流量互通。
• 动态流量伪装：通过 iptables 自动配置 MASQUERADE 规则。脚本能智能识别宿主机的物理网卡名称，实现 NAT 转发，让客户端能够通过服务器访问公网。
• 热加载节点管理：引入 wg syncconf 机制，在添加新 Peer（客户端）时，无需重启整个服务即可实时生效，保证了已有连接的稳定性。

wg_install.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

#!/bin/bash

# ====================================================
# 服务端固定配置
# ====================================================
SERVER_PRIV="your private key"
SERVER_PUB="your public key"
SERVER_PORT=15321
SERVER_IP_RANGE="10.10.10.1/24"
INTERFACE="wg0"
CONF_PATH="/etc/wireguard/${INTERFACE}.conf"

show_help() {
    echo "用法: sudo $0 [选项]"
    echo ""
    echo "选项:"
    echo "  gen                             生成一组全新的客户端密钥对"
    echo "  add [名称] [公钥] [IP/32]       添加一个新的客户端 (例如: add Phone xxxx 10.10.10.5/32)"
    echo "  --help, -h                      显示此帮助信息"
    echo ""
    echo "示例:"
    echo "  首次安装: sudo $0"
    echo "  增加设备: sudo $0 add Node_A xxxxxxxx 10.10.10.3/32"
}

# 处理指令
case "$1" in
    gen)
        command -v wg >/dev/null 2>&1 || sudo apt update && sudo apt install wireguard -y
        _tmp_priv=$(wg genkey)
        _tmp_pub=$(echo "$_tmp_priv" | wg pubkey)
        echo "PRIVATE_KEY: $_tmp_priv"
        echo "PUBLIC_KEY:  $_tmp_pub"
        exit 0
        ;;
    add)
        if [ -z "$3" ] || [ -z "$4" ]; then
            echo "错误: add 指令需要 [名称] [公钥] [IP] 三个参数。"
            exit 1
        fi
        CLIENT_NAME="$2"
        CLIENT_PUB="$3"
        CLIENT_IP="$4"
        ;;
    --help|-h)
        show_help
        exit 0
        ;;
    "")
        # 默认模式：初始化或显示当前状态
        ;;
    *)
        echo "未知指令: $1"
        show_help
        exit 1
        ;;
esac

# 执行逻辑
command -v wg >/dev/null 2>&1 || sudo apt update && sudo apt install wireguard iptables -y
sudo sysctl -w net.ipv4.ip_forward=1
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf > /dev/null

if [ ! -f "$CONF_PATH" ]; then
    ETH_NAME=$(ip route | grep default | awk '{print $5}' | head -n1)
    cat <<EOF | sudo tee $CONF_PATH
[Interface]
PrivateKey = ${SERVER_PRIV}
Address = ${SERVER_IP_RANGE}
ListenPort = ${SERVER_PORT}
PostUp = iptables -A FORWARD -i ${INTERFACE} -j ACCEPT; iptables -t nat -A POSTROUTING -o ${ETH_NAME} -j MASQUERADE
PostDown = iptables -D FORWARD -i ${INTERFACE} -j ACCEPT; iptables -t nat -D POSTROUTING -o ${ETH_NAME} -j MASQUERADE
EOF
fi

if [ -n "$CLIENT_PUB" ]; then
    if grep -q "$CLIENT_PUB" "$CONF_PATH"; then
        echo "提示: 公钥 $CLIENT_PUB 已存在。"
    else
        echo "正在追加 Peer: $CLIENT_NAME ($CLIENT_IP)"
        cat <<EOF | sudo tee -a $CONF_PATH

# $CLIENT_NAME
[Peer]
PublicKey = ${CLIENT_PUB}
AllowedIPs = ${CLIENT_IP}
EOF
    fi
fi

sudo systemctl enable wg-quick@${INTERFACE}
if sudo systemctl is-active --quiet wg-quick@${INTERFACE}; then
    sudo wg syncconf ${INTERFACE} <(sudo wg-quick strip ${INTERFACE})
else
    sudo systemctl start wg-quick@${INTERFACE}
fi
echo "--- 当前 WireGuard 状态 ---"
sudo wg show

二、 常规客户端：交互式简化与自启动

对于标准的 Linux 服务器或虚拟机，部署的重点在于快速入网与开机持久化。

1. 部署亮点

• 交互式配置：通过命令行交互自动获取服务端 IP 与端口，避免手动编辑配置文件的低效。
• MTU 优化策略：针对跨运营商或跨境链路，脚本默认将 MTU 设定为 1280，有效避免了大包在复杂网络节点中被静默丢弃的问题。
• Systemd 托管：通过 systemctl enable 实现服务级别的自启动，确保设备重启后隧道能够自动重连。

wg_install_client.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

#!/bin/bash

# ====================================================
# WireGuard 客户端优化脚本
# 功能：自动安装依赖、密钥管理、配置校验、服务自启
# ====================================================

# 1. 基础配置
CLIENT_WG_IP="10.10.10.4/24"
ALLOWED_IPS="10.10.10.0/24"
SERVER_PUB="dHJLSDvhCkYlDvj/3ic3thYV9rxJfda10SphYZXEcQk="
INTERFACE="wg0"
CONF_PATH="/etc/wireguard/${INTERFACE}.conf"

# 检查 root 权限
[[ $EUID -ne 0 ]] && echo "错误: 请使用 sudo 运行" && exit 1

# 2. 自动安装 WireGuard 相关工具
install_wg() {
    if ! command -v wg &> /dev/null; then
        echo "正在安装 wireguard-tools..."
        if command -v apt-get &> /dev/null; then
            apt-get update && apt-get install -y wireguard resolvconf
        elif command -v yum &> /dev/null; then
            yum install -y epel-release && yum install -y wireguard-tools
        else
            echo "错误: 无法识别的包管理器，请手动安装 wireguard-tools"
            exit 1
        fi
    fi
}

# 3. 交互式输入 (增加验证)
get_server_info() {
    if [ -z "$SERVER_IP" ]; then
        read -p "请输入海外服务器公网 IP: " SERVER_IP
        while [[ ! $SERVER_IP =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; do
            read -p "IP 格式错误，请重新输入: " SERVER_IP
        done
        
        read -p "请输入端口 [15321]: " SERVER_PORT
        SERVER_PORT=${SERVER_PORT:-15321}
    fi
}

# 4. 密钥管理逻辑 (优化提取逻辑)
manage_keys() {
    mkdir -p /etc/wireguard/
    chmod 700 /etc/wireguard/

    if [ -f "$CONF_PATH" ]; then
        CLIENT_PRIV=$(grep "PrivateKey" "$CONF_PATH" | sed 's/ //g' | cut -d'=' -f2)
    fi

    if [ -z "$CLIENT_PRIV" ]; then
        CLIENT_PRIV=$(wg genkey)
        echo "生成新私钥并已存入配置文件。"
        echo "对应的公钥为: $(echo "$CLIENT_PRIV" | wg pubkey)"
    fi
}

# 5. 执行安装与配置
install_wg
get_server_info
manage_keys

# 6. 写入配置
cat <<EOF > "$CONF_PATH"
[Interface]
PrivateKey = ${CLIENT_PRIV}
Address = ${CLIENT_WG_IP}
MTU = 1280

[Peer]
PublicKey = ${SERVER_PUB}
Endpoint = ${SERVER_IP}:${SERVER_PORT}
AllowedIPs = ${ALLOWED_IPS}
PersistentKeepalive = 25
EOF

chmod 600 "$CONF_PATH"

# 7. 启动与验证
echo "正在重启 WireGuard 接口: ${INTERFACE}..."
systemctl stop wg-quick@${INTERFACE} >/dev/null 2>&1

# 启用并启动服务
systemctl daemon-reload
systemctl enable wg-quick@${INTERFACE} >/dev/null 2>&1

if systemctl restart wg-quick@${INTERFACE}; then
    echo "===================================================="
    echo "状态: 启动成功！"
    echo "模式: 安全分流 (仅处理 ${ALLOWED_IPS})"
    echo "测试: ping -c 3 10.10.10.1"
    echo "===================================================="
    wg show "${INTERFACE}"
else
    echo "启动失败，请检查日志: journalctl -xeu wg-quick@${INTERFACE}"
fi

三、 K8s/PM2 深度优化版：攻克容器环境

这是最具挑战性的场景。在 K8s 容器或精简版镜像中，由于缺乏 systemd 守护进程且 /etc/resolv.conf 受到系统严格锁定，传统脚本往往会失效。

1. 探索与突破点分析

• 剔除 resolvconf 依赖：在容器中，/etc/resolv.conf 通常是挂载的只读文件。脚本显式移除了对 resolvconf 的依赖，解决了因文件锁定导致的安装失败问题。
• PM2 进程托管：在没有 systemd 的环境下，利用 PM2 接管隧道。通过一个“包装脚本”执行 wg-quick up 后进入 sleep infinity 状态，欺骗 PM2 维持进程常驻。
• 生命周期管理：利用 Shell 的 trap 机制捕获 SIGTERM 和 SIGINT 信号。当执行 pm2 stop 时，脚本能自动触发 wg-quick down 清理网卡，防止网卡名称冲突。
• 环境变量补全：在容器内，PM2 的运行路径可能不包含 /sbin。脚本通过显式导出 PATH，确保了 ip 和 wg 等核心命令能被正确调用。

wg_install_pm2.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

#!/bin/bash

# ====================================================
# WireGuard 客户端 (PM2 适配版 - K8s 深度优化)
# 修复：移除 resolvconf 依赖，解决 /etc/resolv.conf 被锁定问题
# ====================================================

# 1. 基础配置
CLIENT_WG_IP="10.10.10.3/24"
ALLOWED_IPS="10.10.10.0/24"
SERVER_PUB="dHJLSDvhCkYlDvj/3ic3thYV9rxJfda10SphYZXEcQk="
INTERFACE="wg0"
CONF_PATH="/etc/wireguard/${INTERFACE}.conf"
WRAPPER_PATH="/etc/wireguard/wg_pm2_run.sh"

[[ $EUID -ne 0 ]] && echo "错误: 请使用 sudo 运行" && exit 1

# 2. 强力安装依赖 (剔除 resolvconf)
install_deps() {
    echo "正在清理受损的 resolvconf (如果存在)..."
    apt-get purge -y resolvconf &> /dev/null
    
    echo "正在同步并安装网络工具包 (iproute2, wireguard-tools)..."
    apt-get update && apt-get install -y iproute2 wireguard-tools
    
    if ! command -v ip &> /dev/null; then
        echo "错误: ip 命令安装失败，请检查系统源！"
        exit 1
    fi
}

# 3. 密钥管理 (修复等号截断)
manage_keys() {
    mkdir -p /etc/wireguard/
    chmod 700 /etc/wireguard/
    if [ -f "$CONF_PATH" ]; then
        CLIENT_PRIV=$(grep "PrivateKey" "$CONF_PATH" | sed 's/ //g' | cut -d'=' -f2-)
    fi
    if [ -z "$CLIENT_PRIV" ] || [ ${#CLIENT_PRIV} -lt 43 ]; then
        CLIENT_PRIV=$(wg genkey)
    fi
    CLIENT_PUB=$(echo "$CLIENT_PRIV" | wg pubkey)
    echo "===================================================="
    echo "客户端公钥: $CLIENT_PUB"
    echo "===================================================="
}

# 4. 获取服务端信息
get_server_info() {
    if [ -z "$SERVER_IP" ]; then
        read -p "请输入海外服务器公网 IP: " SERVER_IP
        read -p "请输入端口 [15321]: " SERVER_PORT
        SERVER_PORT=${SERVER_PORT:-15321}
    fi
}

install_deps
get_server_info
manage_keys

# 5. 写入配置 (显式去掉 DNS 选项防止调用 resolvconf)
cat <<EOF > "$CONF_PATH"
[Interface]
PrivateKey = ${CLIENT_PRIV}
Address = ${CLIENT_WG_IP}
MTU = 1380

[Peer]
PublicKey = ${SERVER_PUB}
Endpoint = ${SERVER_IP}:${SERVER_PORT}
AllowedIPs = ${ALLOWED_IPS}
PersistentKeepalive = 25
EOF
chmod 600 "$CONF_PATH"

# 6. PM2 包装脚本 (显式补全环境变量)
cat <<EOF > "$WRAPPER_PATH"
#!/bin/bash
# 确保 PM2 环境能找到 sbin 下的 ip 命令
export PATH=\$PATH:/sbin:/usr/sbin:/usr/local/sbin

function cleanup {
    echo "正在关闭隧道..."
    wg-quick down ${INTERFACE}
    exit
}
trap cleanup SIGTERM SIGINT

echo "正在启动 WireGuard 隧道..."
wg-quick up ${INTERFACE}

echo "隧道运行中..."
sleep infinity
EOF
chmod +x "$WRAPPER_PATH"

# 7. 启动 PM2
if command -v pm2 &> /dev/null; then
    pm2 delete "wg-client" &> /dev/null
    pm2 start "$WRAPPER_PATH" --name "wg-client"
    pm2 save
    echo "配置完成！请检查：pm2 logs wg-client"
else
    echo "未找到 PM2，请手动启动 $WRAPPER_PATH"
fi

四、 实战避坑指南：那些让你握手失败的细节

在探索过程中，我们总结了几个极易忽视的“深坑”：

1. 依赖包的精准补全

精简版镜像往往不含 iproute2。如果报错 ip: command not found，wg-quick 将彻底瘫痪。必须确保安装了此包。

2. 私钥提取的截断问题

在自动化提取旧配置中的私钥时，简单的 cut 命令可能会截断 Base64 末尾的 = 号。WireGuard 对密钥格式有严格要求，任何字符缺失都会导致静默丢包。

3. MTU 的“木桶效应”

如果隧道能 Ping 通但无法加载网页，通常是 MTU 导致的。建议在不稳定的链路中统一使用 1280。

五、 使用建议与工作流

1. 服务端先行：运行服务端脚本初始化网关，生成服务端公钥。
2. 客户端入网：根据环境选择常规版或 PM2 优化版。运行脚本生成客户端公钥后，在服务端执行 add 操作。
3. 持久化验证：重启机器或 PM2 任务，验证隧道是否能自动拉起并恢复握手。

结语：WireGuard 的强大在于其简洁，而部署的难点在于环境的多样性。通过理解 systemd 与 PM2 的托管差异，以及容器对网络配置的特殊限制，我们才能构建出真正“全场景通用”的自动化组网方案。

方案核心优势

1. 自动化集群管理：一键分发实例到不同 GPU，自动配置 CUDA 环境。

2. 双重可靠性守护：结合 PM2 进程守护与自定义 HTTP Watchdog，解决 ComfyUI 进程在位但服务假死的顽疾。

3. 推理性能优化：针对 3090 显卡深度定制，注入 bf16、highvram 及跨注意力优化参数。

4. 智能网关分发：Caddy 自动实现负载均衡，并针对 AI 生成任务的超长连接进行超时优化。

第一部分：ComfyUI 集群服务部署

该脚本负责初始化 Python 虚拟环境调用、生成 PM2 配置文件（ecosystem.config.js）以及启动 HTTP 存活监测。

脚本 1：comfy_pm2_manager.sh

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

#!/bin/bash
# ============================================================
# ComfyUI PM2 Cluster Manager (v2.6)
# ============================================================
set -e

do_install() {
    echo -e ">>> 开始配置 ComfyUI 集群服务..."
    
    # 路径与环境配置
    read -p "1. ComfyUI 目录路径: " WORKSPACE
    WORKSPACE=${WORKSPACE:-/ai/mnt/comfyui}
    read -p "2. pyenv 虚拟环境名称: " PYENV_NAME
    PYENV_NAME=${PYENV_NAME:-comfyui}
    
    PYTHON_EXE="$(eval echo "~$USER")/.pyenv/versions/$PYENV_NAME/bin/python"
    MAIN_PY="$WORKSPACE/main.py"

    read -p "3. 实例总数: " INSTANCE_COUNT

    # 1. 生成 PM2 配置文件
    CONFIG_FILE="$WORKSPACE/ecosystem.config.js"
    echo "module.exports = { apps: [" > $CONFIG_FILE
    declare -a PORTS
    for ((i=1; i<=INSTANCE_COUNT; i++)); do
        read -p "实例 #$i 端口: " PORT
        read -p "实例 #$i 显卡 ID: " GPU_ID
        PORTS+=($PORT)
        cat <<EOF >> $CONFIG_FILE
    {
      name: "comfy-$PORT",
      cwd: "$WORKSPACE",
      script: "$MAIN_PY",
      interpreter: "$PYTHON_EXE",
      args: "--port $PORT --highvram --bf16-unet --use-pytorch-cross-attention --listen 0.0.0.0",
      env: { CUDA_VISIBLE_DEVICES: "$GPU_ID", PYTHONUNBUFFERED: "1" },
      autorestart: true,
      max_memory_restart: '22G'
    },
EOF
    done
    echo "  ] };" >> $CONFIG_FILE

    # 2. 生成 Watchdog 监测脚本 (处理假死)
    WATCHDOG_PATH="$WORKSPACE/comfy_watchdog.sh"
    cat <<EOF > $WATCHDOG_PATH
#!/bin/bash
PORTS=(${PORTS[@]})
while true; do
  for PORT in "\${PORTS[@]}"; do
    HTTP_CODE=\$(curl -s -o /dev/null -w "%{http_code}" --max-time 15 http://127.0.0.1:\$PORT/)
    if [ "\$HTTP_CODE" -ne 200 ]; then
        pm2 restart "comfy-\$PORT"
    fi
  done
  sleep 60
done
EOF
    chmod +x $WATCHDOG_PATH

    # 3. 启动
    pm2 delete /comfy-.*/ 2>/dev/null || true
    pm2 start $CONFIG_FILE
    pm2 start $WATCHDOG_PATH --name "comfy-monitor"
    pm2 save
}

case "$1" in
    install) do_install ;;
    uninstall) pm2 delete /comfy-.*/ 2>/dev/null || true ;;
    *) echo "Usage: $0 {install|uninstall}" ;;
esac

第二部分：Caddy 负载均衡网关

在多实例运行后，需要一个统一入口。Caddy 相比 Nginx 的优势在于配置极其简洁，且天然支持 HTTP/3。

脚本 2：caddy_pm2_setup.sh

此脚本会自动处理端口格式，确保 Caddy 不会将纯数字误认为域名。

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

#!/bin/bash
# ============================================================
# Caddy PM2 自动化部署脚本 (v1.5)
# ============================================================
set -e

# 1. 自动下载 (支持国内镜像加速)
install_caddy() {
    if ! command -v caddy >/dev/null 2>&1; then
        URL="https://mirror.ghproxy.com/https://github.com/caddyserver/caddy/releases/download/v2.7.6/caddy_2.7.6_linux_amd64.tar.gz"
        curl -L "$URL" -o caddy.tar.gz
        tar -zxvf caddy.tar.gz caddy
        mv caddy /usr/bin/ && chmod +x /usr/bin/caddy
        rm caddy.tar.gz
    fi
}

# 2. 生成 Caddyfile 并启动
configure_and_run() {
    read -p "监听端口 (默认 80): " SITE_PORT
    SITE_PORT=${SITE_PORT:-80}
    [[ $SITE_PORT != :* ]] && LISTEN_ADDR=":$SITE_PORT" || LISTEN_ADDR="$SITE_PORT"
    
    read -p "后端 ComfyUI 端口 (空格分隔): " PORTS
    BACKENDS=""
    for p in $PORTS; do
        clean_p=${p#:}
        BACKENDS="$BACKENDS 127.0.0.1:$clean_p"
    done

    cat <<EOF > Caddyfile
$LISTEN_ADDR {
    encode gzip
    reverse_proxy {
        to $BACKENDS
        lb_policy least_conn
        health_uri /
        health_interval 10s
        transport http {
            read_timeout 600s
            write_timeout 600s
        }
    }
    request_body { max_size 1GB }
}
EOF
    pm2 delete caddy 2>/dev/null || true
    pm2 start $(which caddy) --name "caddy" -- run --config ./Caddyfile --adapter caddyfile
    pm2 save
}

install_caddy
configure_and_run

运维管理手册

1. 常用指令

• 查看集群状态：pm2 list

• 查看网关日志（排查连接问题）：pm2 logs caddy

• 查看 ComfyUI 日志：pm2 logs comfy-8188

• 重启整个集群：pm2 restart all

2. 关键配置解析

• **lb_policy least_conn**：最少连接数优先。这对于 AI 推理至关重要，因为有的请求（如视频生成）耗时极长，该策略能确保新请求发往空闲实例。

• **read_timeout 600s**：将超时阈值提升至 10 分钟。默认网关通常在 60s 后断开，会导致长耗时工作流前端报错。

• **CUDA_VISIBLE_DEVICES**：通过环境变量精确锁定每个进程可见的 GPU，避免多实例竞抢同一张卡的显存。

卸载与清理

如需移除服务，可运行 pm2 delete caddy /comfy-.*/。本方案在清理时采用正则匹配，绝不会误伤服务器上的其他关键服务。

本文将带你快速完成 OpenClaw 与 Home Assistant 的联动配置。

1. 准备工作

• 成功部署了OpenClaw
• 拥有一个可内网或外网访问的Home Assistant

2. 在 Home Assistant 中生成令牌

为了让 OpenClaw 有权操作你的设备(建议新建一个用户,不要设为管理员,也不要用你的管理员账户生成token)，需要生成一个 **长期访问令牌 (Long-Lived Access Token) **：

1. 登录你的 Home Assistant 面板。
2. 点击左下角的 个人头像（用户资料）。
3. 滚动到底部，找到 长期访问令牌 栏目。
4. 点击 创建令牌，命名为 OpenClaw。
5. 复制并保存 弹出的字符串（注意：关闭后将无法再次查看）。

3. OpenClaw 端配置

安装技能

在OpenClaw的聊天对话框(或其他你已经配置的channel),告诉openclaw:

1

帮我安装home assistant skill，也可以根据你的需求进行安装

配置Home Assistant参数

修改config.json,如果没有就复制example来修改,设置url和token,注意url不要设置localhost或127.0.0.1(HA可能跟openclaw不在一个服务器)

这里的参数配置,也可以让openclaw自己来完成.

4. 常用指令与测试

配置完成后，你可以尝试通过 OpenClaw（例如在 Telegram 或微信中）向它下达指令：

“帮我打开客厅的灯。”
“现在主卧的温度是多少？”
“帮我关掉家里所有的电器。”

OpenClaw 会调用 HA 的 API 自动识别实体 ID 并执行操作。

5. 常见问题 (FAQ)

• 无法连接？ 检查 HA 是否开启了防火墙，或者 OpenClaw 所在服务器是否能 Ping 通 HA 地址。
• 找不到设备？ 请确保在 HA 中为设备设置了易于识别的“别名”（Friendly Name），这样 AI 识别率更高。

什么是 OpenClaw？

OpenClaw 是一个开源的 AI 助手运行时，核心特点：

• 多平台支持 - WhatsApp、Telegram、飞书、Discord 等
• 工具扩展 - 文件操作、网页搜索、浏览器自动化等
• 本地部署 - 数据完全掌控，支持私有模型
• 技能系统 - 模块化扩展，自定义工作流

系统要求

• Node.js: 24+ 推荐（22 LTS 也支持）
• 系统: macOS、Linux 或 Windows（WSL2）
• 内存: 最低 1GB，推荐 2GB+
• 存储: 约 500MB（不含模型）

检查 Node 版本：

1
2

node --version
# 应显示 v22.16+ 或 v24+

快速安装

方式一：安装脚本（推荐）

macOS / Linux:

1

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell):

1

iwr -useb https://openclaw.ai/install.ps1 | iex

安装脚本会自动：

1. 检测并安装合适的 Node.js 版本
2. 安装 OpenClaw CLI
3. 启动配置向导

方式二：npm 手动安装

如果已管理 Node.js 环境：

1
2

npm install -g openclaw@latest
openclaw onboard --install-daemon

注意: 如果遇到 sharp 构建错误（macOS 常见），使用：

1 2 3 4 5 6 7 8 9 10 11 12 13

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest ```bash ### 方式三：Docker 部署 适合服务器或隔离环境： ```bash docker run -d \ --name openclaw \ -p 18789:18789 \ -v openclaw-data:/root/.openclaw \ openclaw/openclaw:latest

访问 http://localhost:18789 查看控制面板。

初始化配置

安装完成后，运行配置向导：

1

openclaw onboard --install-daemon

向导会引导你完成：

1. 选择 AI 模型 - 支持 OpenAI、Anthropic、智谱、通义千问等
2. 配置认证 - 输入 API Key
3. 选择渠道 - WhatsApp、Telegram、飞书等（可跳过）
4. 安装服务 - 将 Gateway 注册为系统服务

模型推荐

启动和验证

检查服务状态

1

openclaw gateway status

正常输出应显示服务运行中。

打开控制面板

1

openclaw dashboard

或访问 http://127.0.0.1:18789/

在控制面板中，你可以：

• 直接对话测试
• 查看会话历史
• 配置模型和渠道
• 管理技能和工具

发送测试消息

如果配置了渠道（如飞书）：

1
2
3

openclaw message send \
  --target "用户 ID" \
  --message "Hello from OpenClaw"

配置渠道（可选）

飞书（Feishu）

1. 创建飞书应用：https://open.feishu.cn/app
2. 获取 App ID 和 App Secret
3. 配置回调 URL：https://你的域名/openclaw/feishu
4. 添加到配置文件：

1

openclaw config edit

添加配置：

1
2
3
4

channels:
  feishu:
    appId: cli_xxxxxxxxxxxxx
    appSecret: xxxxxxxxxxxxxxx

WhatsApp

1. 运行：openclaw channels whatsapp setup
2. 扫描二维码绑定
3. 完成配置

Telegram

1. 联系 @BotFather 创建机器人
2. 获取 Token
3. 配置：openclaw channels telegram add <token>

使用技能

OpenClaw 支持技能扩展，例如：

查看可用技能

1

ls ~/.openclaw/workspace/skills/

使用技能对话

直接在聊天中说明需求：

• “帮我写一篇技术博客” → 使用 hexo-blogger 技能
• “检查天气” → 使用 weather 技能
• “搜索 GitHub issues” → 使用 gh-issues 技能

创建自定义技能

参考官方文档：技能创建指南

常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 查看状态
openclaw status
openclaw gateway status

# 重启服务
openclaw gateway restart

# 查看日志
openclaw gateway logs

# 更新版本
openclaw update

# 打开配置
openclaw config edit

# 查看帮助
openclaw --help

故障排查

Gateway 无法启动

1
2
3
4
5
6
7
8

# 查看详细日志
openclaw gateway logs --follow

# 检查端口占用
lsof -i :18789

# 手动前台运行测试
openclaw gateway --port 18789

模型调用失败

1. 检查 API Key 是否正确
2. 验证网络连接
3. 查看配额限制

1
2

# 测试模型连接
openclaw models test <model-name>

渠道消息不响应

1. 检查渠道是否启用
2. 验证回调 URL 配置
3. 查看渠道日志

进阶配置

自定义工作目录

1

export OPENCLAW_HOME=/path/to/your/workspace

配置文件位置

• 配置: ~/.openclaw/config.json
• 工作区: ~/.openclaw/workspace/
• 日志: ~/.openclaw/logs/

环境变量

下一步

• 📚 官方文档
• 💬 Discord 社区
• 🛠️ 技能中心
• 🔧 自定义工具开发

参考信息:

• 当前版本：OpenClaw 2026.3.13
• Node.js 版本：v24.10.0
• 文档更新日期：2026-03-21

1️⃣ 多平台快速安装

提示：Linux 版的脚本会自动把 ollama 二进制放到系统路径下，并创建 ollama 系统服务，后续可以用 systemctl 管理。

2️⃣ 环境变量 & 服务配置

Ollama 通过环境变量控制监听地址、模型存储路径、并发数等。不同系统的配置方式略有差异。

2.1 常用环境变量（跨平台）

2.2 默认模型存放路径

2.3 OS‑Specific 设置方法

小技巧：修改完变量后，务必 重启 Ollama（或重新加载 systemd）让新配置生效。

3️⃣ 核心 CLI 命令一览

下面列出常用的 ollama 子命令，配合 --help 可查看完整参数说明。

实战：想把 qwen3:30b 直接拉取并对话，只需一行 ollama run qwen3:30b。

4️⃣ 常用模型快速上手

Ollama 官方库提供了多种模型，下面列出常见几款及对应的拉取命令（模型大小在括号，单位 GB）【6†L51-L65】。

1
2
3
4

ollama run qwen3:235b        # 23bB, 142GB
ollama run qwen3:30b         # 30B, 18GB
ollama run deepseek-r1:32b  # 32B, 19GB 
ollama run qwen3-vl:8b      # 8B, 6.1GB (Vision)

内存要求：

• 8 GB RAM 可运行 7B 模型；
• 16 GB RAM 推荐运行 13B 以上模型；
• 32 GB+ RAM 可流畅运行 33 B+ 大模型。

5️⃣ 自定义模型（Modelfile）

5.1 Modelfile 基本语法

1
2

# comment
INSTRUCTION arguments

常用指令包括：

示例（基于 llama3.2，温度 1、上下文 4096、系统提示）：

1
2
3
4

FROM llama3.2
PARAMETER temperature 1
PARAMETER num_ctx 4096
SYSTEM You are Mario from Super Mario Bros, answering as Mario.

5.2 创建 & 运行自定义模型

1
2
3
4
5
6
7
8
9
10
11
12

# 1️⃣ 保存为 Modelfile
cat > Modelfile <<EOF
FROM llama3.2
PARAMETER temperature 1
SYSTEM You are Mario...
EOF

# 2️⃣ 构建模型
ollama create mario -f Modelfile   

# 3️⃣ 使用模型
ollama run mario

温度 / 上下文：在交互式会话里也可以随时通过 /set parameter 调整，例如 /set parameter num_ctx 4096。

6️⃣ GPU 加速与并发控制

6.1 GPU 兼容性

官方文档提供 GPU 兼容列表（NVIDIA、AMD ROCm 等）。

• Linux 上使用 curl 安装的版本会自动检测并使用 CUDA。
• Windows 需要 WSL2 + NVIDIA 驱动或直接在本地（自 0.1.33 起原生支持）。

6.2 查看模型是否在 GPU 上运行

ollama ps 会显示每个模型的 Processor 列，100% GPU 表示已完全加载到显存。

6.3 并发请求 & 资源限制

调优思路：显存足够时，可适当提升 OLLAMA_NUM_PARALLEL；若出现 OOM，需要降低 OLLAMA_MAX_LOADED_MODELS 或 NUM_PARALLEL。

7️⃣ REST API 与 SDK 示例

Ollama 提供标准的 HTTP 接口，适配所有语言。下面展示最常用的 generate 与 chat 两个端点。

7.1 单轮生成（/api/generate）

1
2
3
4
5

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?",
  "options": { "num_ctx": 4096 }
}'

num_ctx 用于扩大上下文窗口。

7.2 多轮对话（/api/chat）

1
2
3
4
5
6
7

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role":"user","content":"What is the meaning of life?"},
    {"role":"assistant","content":"42"}
  ]
}'

7.3 Python SDK（简要示例）

1
2
3
4
5
6
7
8
9

from ollama import Client

client = Client(host="http://localhost:11434")
resp = client.generate(
    model="phi3",
    prompt="写一段 Python 的冒泡排序代码",
    options={"temperature": 0.7}
)
print(resp["response"])

官方 Python SDK 与 JS SDK 均已发布，可在 GitHub 上获取。

8️⃣ 常见问题 & 调试技巧

9️⃣ 社区 UI 与生态集成

选用 UI 取决于使用场景：如果仅在终端玩模型，CLI 足矣；若需要多人协作或可视化对话，推荐 Open WebUI。

🎉 小结

• 一步到位：curl … | sh → ollama run llama3.2。
• 灵活配置：环境变量让你随意搬迁模型、暴露端口、调节并发。
• GPU 与并发：ollama ps 检查显卡加载，OLLAMA_NUM_PARALLEL / OLLAMA_MAX_LOADED_MODELS 控制资源。
• 自定义：通过 Modelfile 定制系统提示、参数、LoRA 适配器。
• API & SDK：REST 与官方 SDK 让模型轻松嵌入任意应用。

现在，你已经拥有从 安装、配置、模型管理 到 API 调用 的完整知识链，快去本地跑通你的第一个大模型吧！ 🚀

本文所有命令均已在最新的 Ollama 0.1.43（截至 2025‑11‑18）上测试通过，若有版本差异，请参考官方文档。

还在为AI生成的内容空洞、跑题或完全不符合预期而烦恼吗？你不是一个人。与AI有效沟通的关键，在于掌握“提问的艺术”。而Prompt框架，正是将这门艺术系统化、科学化的终极武器。

0x00 为什么你需要Prompt框架？

想象一下，你是一位项目经理，需要AI帮你写一份项目计划书。如果你只是说：“写一份项目计划书”，AI可能会给你一份泛泛而谈、毫无用处的模板。

但如果你能清晰地告诉AI：

• 角色： 扮演一位资深的IT项目经理。
• 目标： 为一款新的移动应用制定一个3个月的上市计划。
• 背景： 团队有5人，预算有限，需要突出敏捷开发方法。
• 要求： 包含目标、里程碑、风险分析和预算概算，以Markdown表格形式呈现。

结果会如何？AI的输出将瞬间变得具体、专业且可直接使用。

这个例子背后，就隐含了一个简单的框架。Prompt框架是一套结构化的模板，它指导你如何组织指令，确保向AI传递完整、清晰且无歧义的信息。 它的核心价值在于：

1. 提升效率： 减少来回修改和迭代的次数，一次生成高质量内容。
2. 确保完整性： 框架像一张清单，提醒你覆盖所有关键要素，避免遗漏。
3. 降低门槛： 即使你不是领域专家，也能通过框架引导AI产出专家级内容。
4. 结果可预测： 结构化的输入带来稳定、可预期的输出。

接下来，我们将深入探讨几个备受推崇的精选Prompt框架，助你从AI新手秒变Prompt高手。

0x01 四大精选Prompt框架详解

框架一：CRISPE——全能型选手，最受推崇的框架之一

CRISPE框架非常全面，尤其适合处理复杂任务。它由六个核心维度构成：

• C - Capacity and Role (能力与角色)： 你希望AI扮演什么角色？（例如：一位资深的数据科学家、一位风趣的营销文案写手、一位严格的语法老师）
• R - Result (结果)： 你希望最终达成什么目标？请具体描述理想的输出。（例如：生成一份包含5个要点的清单、写一篇1000字的博文、输出一段可运行的Python代码）
• I - Intent (意图)： 你为什么需要这个结果？你的深层目的是什么？（例如：是为了教育小白用户、是为了做一个市场分析报告、是为了调试一段程序）
• S - Steps (步骤)： 为实现结果，需要遵循哪些具体的步骤？（这一步是可选的，但对于复杂任务至关重要）
• P - Personalization (个性化)： 你希望输出的风格、语调或格式是怎样的？（例如：正式、幽默、简洁；以Markdown格式输出；使用比喻和例子）
• E - Experiment (实验)： 如果对初次结果不满意，如何改进？邀请AI提供变体或征求反馈。

CRISPE实战示例：

【角色】 你是一名经验丰富的健康营养师。
【结果】 为我制定一份为期一周的、适合素食者的减脂午餐食谱清单。
【意图】 这份食谱需要简单易做，食材容易购买，目标是帮助忙碌的上班族健康瘦身。
【步骤】 请按以下步骤提供：1. 列出7天的午餐食谱名称。2. 为每一道菜提供详细的食材清单和烹饪步骤。3. 标注每餐的预估卡路里。
【个性化】 语言风格请保持鼓励和亲切，最后用一句励志名言结尾。
【实验】 如果你能同时提供一些替换食材的建议，以备不时之需，那将非常棒。

框架二：BROKE——谈判专家与需求澄清利器

BROKE框架模拟了一种“谈判”或“需求确认”的过程，非常适合在项目开始前与AI对齐目标，确保双方理解一致。

• B - Background (背景)： 提供所有相关的背景信息。发生了什么事？现状如何？
• R - Request (请求)： 清晰、直接地提出你的核心要求。
• O - Outcome (成果)： 描述你期望的最终成果是什么样子。成功的标准是什么？
• K - Key Information (关键信息)： 列出任何限制条件、必须包含的要素或需要避免的坑。
• E - Evaluation (评估)： 询问AI是否理解任务，或者让它提出改进建议。

BROKE实战示例：

【背景】 我们团队正在开发一个面向Z世代的社交APP，主打“兴趣社交”。目前产品即将进入市场推广阶段。
【请求】 为我们构思3个核心营销口号。
【成果】 口号需要朗朗上口，能瞬间抓住Z世代的注意力，并能传达“找到同好”的核心价值。
【关键信息】 口号长度不超过10个字，避免使用过时的网络用语。需要考虑到不同性别和文化背景的包容性。
【评估】 请根据以上信息，确认你是否理解任务，并在给出口号后，简要解释每个口号的创意出发点。

框架三：RTF——简洁高效的指令核心

如果你追求速度和简洁，RTF框架是最佳选择。它抓住了有效Prompt最核心的三个要素。

• R - Role (角色)： 指定AI扮演的角色。
• T - Task (任务)： 明确需要完成的具体任务。
• F - Format (格式)： 明确要求输出的格式。

RTF实战示例：

【角色】 你是一位金融分析师。
【任务】 总结特斯拉(TSLA)在2023年第二季度最主要的三个财务亮点和两个潜在风险。
【格式】 用项目符号列表呈现，最后附上一个简单的SWOT分析表格。

框架四：TAG——内容创作的黄金圈法则

TAG框架源于经典的“黄金圈”理论，从内到外（Why -> How -> What）思考，特别适合内容创作、故事编写和战略规划。

• T - Task (任务)： 最终要交付的具体产出是什么？（例如：写一个故事、设计一个方案）
• A - Action (行动)： 为了实现任务，需要采取哪些关键行动或步骤？（例如：先构思人物，再设计冲突，最后写结局）
• G - Goal (目标)： 你最终想达成的深层目标或影响是什么？（例如：让读者感受到希望、说服客户购买产品）

TAG实战示例：

【目标】 创作一个能激发小学生对天文学兴趣的短篇科幻故事。
【行动】 故事需要：1. 以一个孩子的好奇心为起点。2. 包含一个关于黑洞的奇妙想象。3. 结尾要温暖并留有悬念。
【任务】 写一篇800字左右的短篇故事。

0x02 如何选择与组合使用这些框架？

没有哪个框架是万能的。聪明的做法是根据任务类型灵活选择和组合。

• 日常简单任务： 使用 RTF，快速直接。
• 内容创作与复杂任务： 使用 CRISPE 或 TAG，确保深度和创意。
• 项目启动与需求对齐： 使用 BROKE，像与合作伙伴一样与AI沟通。
• 组合使用： 你可以用 BROKE 来确认需求，然后用 CRISPE 来执行具体的创作任务。例如，先和AI用BROKE框架“开个会”，明确需求后，再说：“好的，现在请按照CRISPE框架，以[角色]的身份，开始[任务]…”

0x03 实战演练：用CRISPE框架写一篇博文

任务： 使用AI为一家新开的精品咖啡店写一篇微信公众号推广文章。

完整Prompt如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

【Capacity and Role】 请你扮演一位资深美食博主和咖啡爱好者，文笔细腻且富有感染力。

【Result】 输出一篇约1200字的微信公众号文章，旨在推广一家新开的名为“隅间咖啡”的精品咖啡店。文章需要有一个吸引人的标题和3个小标题，内容要能引发读者的共鸣和探店欲望。

【Intent】 这篇文章的目的是为新店引流，建立品牌初期的好感和知名度，而不仅仅是提供信息。

【Steps】
1.  首先，从一个具体的生活场景或感受切入，引出对一家“理想咖啡店”的渴望。
2.  然后，自然地引入“隅间咖啡”，介绍它的地理位置和外观氛围。
3.  重点描述店内的特色：例如，店主对咖啡豆的严选、独特的手冲工艺、一款招牌产品（如“桂花拿铁”）。
4.  分享一个关于店主开店初心的小故事，增加人情味。
5.  最后，给出店铺的详细信息（地址、营业时间）并以一个温暖的邀请结尾。

【Personalization】 语言风格要求温暖、治愈、有画面感，像在和朋友分享一个秘密基地。避免使用过于商业化的词汇。在文章适当位置，提示可以插入图片（用[图：描述]表示）。

【Experiment】 请为这篇文章提供两个不同风格的标题备选。

通过这个结构化的指令，AI生成的文章会远超一句简单的“写一篇推广隅间咖啡店的公众号文章”。

0x04 总结与进阶技巧

掌握Prompt框架，意味着你从“随机提问”进入了“结构化沟通”的新阶段。记住这几个核心心法：

1. 先模仿，后创造： 熟练掌握1-2个框架，内化成你的思维习惯。
2. 迭代优化： 没有一个Prompt是完美的。如果结果不理想，分析是框架中哪个环节没到位，然后修改再试。
3. 提供上下文： 背景和信息越多，AI的理解越深，输出质量越高。
4. 善用“继续”： 对于长文生成，如果AI中途停止，简单地输入“继续”或“请完成它”即可。

现在，就打开你的AI工具，选择一个你感兴趣的任务，尝试用上面的任何一个框架来重新构建你的Prompt吧。你会发现，一个精心设计的提问，带来的回报是惊人的。

0x00 相关镜像

1
2
3

ilovn/media_sync
ilovn/media302
ilovn/115upload # 非必需,主要用来在远端上传资源用,可以用其他工具替代(实时性降低)

不管你部署在哪里,首先确保你能随时获取到这几个镜像的更新.

0x01 授权问题

因之前media302被小黄鱼上商家滥用,目前3个镜像均需要获取授权后才能正常使用,谢谢合作.授权获取: https://t.me/MediaLicenseBot

0x02 部署

0x021 部署MediaSync

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

mkdir -p /data/mediasync && \
docker pull ilovn/media_sync:latest && \
docker run -d -t --restart always \
-v /data/mediasync:/usr/src/app/config \
-v /mnt:/mnt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e PUID=1000 \
-e PGID=1000 \
-e License="从授权机器人处获取的MediaSync授权密钥" \
-p 8100:8100 \
--name mediasync \
ilovn/media_sync:latest


docker logs -f --tail 200 mediasync

0x022 部署Media302

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
-e EMBY_TOKEN="d8c8a307cb7*******a3a6941f4c3" \
-e UPSTREAM_115_SERVER="http://172.17.0.1:8100/115" \
-e REPLACE_PATH_1="/mnt/strm/Media" \
-e REPLACE_PATH_2="/Media" \
-e License="从授权机器人处获取的Media302授权密钥" \
--name media302 \
-p 8090:8090 \
ilovn/media302:latest

docker logs -f --tail 200 media302

0x023 部署115Upload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

docker pull ilovn/115upload:latest && \
docker run -d -t --restart always \
-v /home/cat/115-cat-cookies.txt:/usr/src/app/115-cookies.txt \
-v /mnt:/mnt \
-e SRC_PATH="/mnt/AutoLink" \
-e DST_PATH="/Media" \
-e MAX_WORKERS=4 \
-e INTERVAL=60 \
-e USE_API="true" \
-e API_SERVER="http://172.17.0.1:8100/api/receive" \
-e Access_Token="xxx-xxx-xxx" \
-e License="从授权机器人处获取的115Upload授权密钥" \
--dns=223.5.5.5 \
--log-driver=local \
--name 115upload \
ilovn/115upload:latest

docker logs -f --tail 200 115upload

0x03 简单配置说明

MediaSync是有配置界面的,部署成功后,访问IP:8100登录即可,默认用户名admin,默认密码root

首次进入会要求完成初始化配置,请按照界面要求完成即可,完成后可以手动执行strm生成或在设置中设置定时任务.

MediaSync配置完成,并切正常生成strm后,建议重启一次MediaSync.

将你的emby媒体库指向MediaSync生成的文件目录,扫描并确认emby可以播放后,准备配置Media302.

Media302常规使用的话,请不要配置emby_token参数,如需图片302,可使用MediaSync的302服务IP:8100/115

0x04 后话

当前方案不涉及Clouddrive(cd2)以及alist等工具,目前正常使用也不会有类似扫库429问题,如果动手能力弱,可以在获取授权后联系我,支持收费协助部署.

0x05效果图

安装

docker安装

• -v /data/mediasync:/usr/src/app/config用于设置配置目录映射
• /mnt:/mnt主要用于映射strm生成
• -v /etc/timezone:/etc/timezone:ro 和-v /etc/localtime:/etc/localtime:ro用于docker和宿主机同步时区,非必需
• -e PUID=1000和-e PGID=1000用于设置docker用户
• -e License="Your License"配置你的授权密钥
• -p 8100:8100端口映射,如需修改,只需将第一个8100改为你想要的端口即可

启动后,通过你的ip:8100即可访问,默认登录用户admin密码root

1
2
3
4
5
6
7
8
9
10
11
12
13

docker pull ilovn/media_sync:latest && \

docker run -d --restart always \
-v /data/mediasync:/usr/src/app/config \
-v /mnt:/mnt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e PUID=1000 \
-e PGID=1000 \
-e License="Your License" \
-p 8100:8100 \
--name mediasync \
ilovn/media_sync:latest

初始化设置

扫码或提供Cookie字符串设置账户

设置同步目录

• 可以通过点击添加目录增加更多目录,生成strm都会保存到输出目录中.

• Token是配合115Upload上传使用的,115Upload使用

  -e API_SERVER="http://172.17.0.1:8100/api/receive" \

  -e Access_Token="your token" \

• 服务地址是strm文件生成的时候的链接地址,搭配media302的后端,可以直接填写对应的地址,比如:http://172.17.0.1:8091注意地址最后不要带/

• 输出目录是保存strm的路径,记得把你的路径挂载到docker容器,这里会校验能不能写入目录

• 路径替换是可选项,用于一些定制场景,比如你的网盘路径是/Media/Movies/XXXX,你觉得加上strm保存路径/mnt/strm后的/mnt/strm/Media/Movies/XXXX太长,可以通过/Media/:/替换掉/Media/为/,实际输出路径为/mnt/strm/Movies/XXXX,注意路径替换是基于:分割

设置strm参数

根据自己的需要设置即可,

以上一步设置的服务地址为http://172.17.0.1:8091为例:

开启短链

包含pickcode:http://172.17.0.1:8091/一人之下 - S01E01.mkv?pickcode=e0lx8xxxxxxxx

包含sha1: http://172.17.0.1:8091/一人之下 - S01E01.mkv?pickcode=e0lx8xxxxxxxx&sha1=D0BCFFE9E91D0E35B2F67F7646A3EDF6FFDCE80E

包含path:http://172.17.0.1:8091/一人之下 - S01E01.mkv?pickcode=e0lx8&sha1=D0BCFFE9E91D0E35B2F67F7646A3EDF6FFDCE80E&path=/Media/Animes/国漫/一人之下/S01/一人之下 - S01E01.mkv

关闭短链

包含pickcode:http://172.17.0.1:8091/Media/Animes/国漫/一人之下/S01/一人之下 - S01E01.mkv?pickcode=e0lx8xxxxxxxx

包含sha1: http://172.17.0.1:8091/Media/Animes/国漫/一人之下/S01/一人之下 - S01E01.mkv?pickcode=e0lx8xxxxxxxx&sha1=D0BCFFE9E91D0E35B2F67F7646A3EDF6FFDCE80E

包含path:http://172.17.0.1:8091/Media/Animes/国漫/一人之下/S01/一人之下 - S01E01.mkv?pickcode=e0lx8&sha1=D0BCFFE9E91D0E35B2F67F7646A3EDF6FFDCE80E&path=/Media/Animes/国漫/一人之下/S01/一人之下 - S01E01.mkv

设置emby通知

设置是否开启emby刷新通知.

• Emby地址:emby的服务地址
• API Token:emby的api token
• 路径替换:用于strm本地路径与emby路径不一致的情况,主要是考虑到当前容器的挂载和emby容器挂载路径不一致的情况.路径替换以:分割,路径是容器内路径为基础,不要随便挂乱七八糟的路径,除非你理解自己的动作

设置定时任务

• 初始化配置完成后,服务已经能够正常接受115Upload的上传通知实现局部更新了.

• 为了首次使用,可以选择主页的意见生成功能实现初始数据落地,这里耗时可能比较长,请耐心等待或者关注容器日志.

• 定时任务会按照设置,定时刷新初始化设置里面的目录,如果目录数据量极大(单文件夹10万文件内最佳),建议分为多个目录使用,效率提升会很明显

  

首页

可以手动执行具体的刷新任务.

0x00 现状

目前构建了3个docker镜像,分别对应文件上传、生成strm、302播放(含图片302):

1
2
3

ilovn/115upload
ilovn/media_library_sync
ilovn/media302

0x01 建议方案

之所以会有所谓的建议方案,主要是很多人其实不理解到底要做什么?如果你仅仅需要一个工具,把你现在已经是alist后端,生成了strm的emby在302上发挥作用,那么下面这几行命令就是你需要的:

1
2
3
4
5
6
7

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
--name media302 \
-p 8090:8090 \
ilovn/media302:latest

其中,UPSTREAM_HOST是你的emby服务器,确保media302所在的环境能访问到即可,然后在你的客户端、网页用media302所在的ip和8090端口访问,你的302就可用了.

注意,cd2本身不支持302访问,所以你的strm里面的地址,请认真检查是http/https开头,并确保是类似alist这种支持302的服务提供的.

总有些人在啥都不懂的情况下,看了后面的方案开始BB,要cookie、要配置很多,拜托,你的需求是什么自己想清楚了就瞎BB,爱用不用.

0x02 media302完整方案

之前有网友联系,即使是小白,其实也可以很快配置出来,而且,提供cookie后,media302能给你提供一个直接可用的302服务端,这也是为什么说可以抛弃alist的原因.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-v /data/115/115-cookies.txt:/usr/src/app/115-cookies.txt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
-e EMBY_TOKEN="emby token" \
-e UPSTREAM_115_SERVER="http://127.0.0.1:8091" \
-e REPLACE_PATH_1="/mnt/strm" \
-e REPLACE_PATH_2="/Media" \
--name media302 \
-p 8090:8090 \
-p 8091:8091 \
ilovn/media302:latest

详细使用,可以参考家庭媒体库方案(六):302方案(图片302优化方案,含后端)

同时有了这个服务端,可以通过caddy这类工具,把这个服务暴露出来:

1
2
3
4
5
6
7
8

xxx.xxx.xxx {
  handle_path /d/115/* {
        reverse_proxy http://127.0.0.1:8091
  }
  handle_path /static/* {
        reverse_proxy http://127.0.0.1:8091
  }
}

0x03 文件上传

这个镜像很简单,就是纯粹的上传,上传并发、上传后删除文件等,都是可配置的:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

docker pull ilovn/115upload:latest && \
docker run -d -t --restart always \
-v /home/cat/115-cat-cookies.txt:/usr/src/app/115-cookies.txt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-v /mnt:/mnt \
-e SRC_PATH="/mnt/AutoLink" \
-e DST_PATH="/Media" \
-e MAX_WORKERS=3 \
-e INTERVAL=60 \
-e USE_API="true" \
-e API_SERVER="http://xxx.xxx.xxx:8092/api/receive" \
-e Access_Token="your token haha" \
--log-driver=syslog \
--name 115upload \
ilovn/115upload:latest

补充说明一下,-t参数,才能让你在docker的log看到上传进度. API_SERVER指向下一步的生成strm的容器,后面的/api/receive不能修改,记得自定义一个Access_Token,两个容器要一样才能工作.

0x04 生成strm

这个方案目前基本稳定,我自己在用,有问题也会处理. 详细可参考:家庭媒体库方案(七):媒体库管理和更新方案

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

sudo docker pull ilovn/media_library_sync:latest && \
sudo docker run -d --restart always \
-v /data/medialibsync/115-cookies.txt:/usr/src/app/115-cookies.txt \
-v /data/medialibsync/db:/usr/src/app/db \
-v /mnt:/mnt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e PUID=1000 \
-e PGID=1000 \
-e FILE_SITE="https://xxx.xxx.xxx/static" \
-e EMBY_SITE="http://172.17.0.1:8096" \
-e EMBY_TOKEN="emby token" \
-e STRM_DIR="/mnt/strm" \
-e REPLACE_STRM_PATH="/Media" \
-e OVERWRITE="false" \
-e NEED_NFO="true" \
-e NEED_IMAGE="false" \
-e JOB_INTERVAL="5" \
-e INIT_QUICK_SCAN="true" \
-e SCAN_DIRS="/Media/Animes|/Media/Movies|/Media/TVShows" \
-e Access_Token="your token haha" \
-p 8092:8092 \
--name medialibsync \
ilovn/media_library_sync:latest

增加了端口映射,作为上传的通知服务端.记得设置Access_Token,两个容器要一样才能工作.

0x05 答疑

1. 为什么不整理成一个镜像?
   很简单, 专业的工具做专业的事情,同时也利于大家分散部署,比如你的PT下载可能是在欧洲,emby可能在国内或者香港、新加坡等,分散部署可以让工具聚焦自己的主力工作,上传的就专业做上传就行.同理,302可以部署在国内,提升302请求的响应速度.

2. media302用域名的时候,infuse不支持图片302
   这是infuse的bug

3. media302支持strm和本地混合吗?
   不支持,我没这诉求

4. media302会支持plex、jellyfin吗?
   不搞了,没意思

0x00 现状

目前构建了3个docker镜像,分别对应文件上传、生成strm、302播放(含图片302):

1
2
3

ilovn/115upload
ilovn/media_library_sync
ilovn/media302

0x01 建议方案

之所以会有所谓的建议方案,主要是很多人其实不理解到底要做什么?如果你仅仅需要一个工具,把你现在已经是alist后端,生成了strm的emby在302上发挥作用,那么下面这几行命令就是你需要的:

1
2
3
4
5
6
7

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
--name media302 \
-p 8090:8090 \
ilovn/media302:latest

其中,UPSTREAM_HOST是你的emby服务器,确保media302所在的环境能访问到即可,然后在你的客户端、网页用media302所在的ip和8090端口访问,你的302就可用了.

注意,cd2本身不支持302访问,所以你的strm里面的地址,请认真检查是http/https开头,并确保是类似alist这种支持302的服务提供的.

总有些人在啥都不懂的情况下,看了后面的方案开始BB,要cookie、要配置很多,拜托,你的需求是什么自己想清楚了就瞎BB,爱用不用.

0x02 media302完整方案

之前有网友联系,即使是小白,其实也可以很快配置出来,而且,提供cookie后,media302能给你提供一个直接可用的302服务端,这也是为什么说可以抛弃alist的原因.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-v /data/115/115-cookies.txt:/usr/src/app/115-cookies.txt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
-e EMBY_TOKEN="emby token" \
-e UPSTREAM_115_SERVER="http://127.0.0.1:8091" \
-e REPLACE_PATH_1="/mnt/strm" \
-e REPLACE_PATH_2="/Media" \
--name media302 \
-p 8090:8090 \
-p 8091:8091 \
ilovn/media302:latest

详细使用,可以参考家庭媒体库方案(六):302方案(图片302优化方案,含后端)

同时有了这个服务端,可以通过caddy这类工具,把这个服务暴露出来:

1
2
3
4
5
6
7
8

xxx.xxx.xxx {
  handle_path /d/115/* {
        reverse_proxy http://127.0.0.1:8091
  }
  handle_path /static/* {
        reverse_proxy http://127.0.0.1:8091
  }
}

0x03 文件上传

这个镜像很简单,就是纯粹的上传,上传并发、上传后删除文件等,都是可配置的:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

docker pull ilovn/115upload:latest && \
docker run -d \
--restart always \
-v /home/cat/115-cat-cookies.txt:/usr/src/app/115-cookies.txt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-v /mnt:/mnt \
-e SRC_PATH="/mnt/AutoLink" \
-e DST_PATH="/Media" \
-e MAX_WORKERS=3 \
-e MAX_RETRIES=5 \
-e INTERVAL=60 \
-e REMOVE_DONE="true" \
--log-driver=syslog \
--name 115upload \
ilovn/115upload:latest

0x04 生成strm

这个方案目前基本稳定,我自己在用,有问题也会处理. 详细可参考:家庭媒体库方案(七):媒体库管理和更新方案

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

sudo docker pull ilovn/media_library_sync:latest && \
sudo docker run -d --restart always \
-v /data/medialibsync/115-cookies.txt:/usr/src/app/115-cookies.txt \
-v /data/medialibsync/db:/usr/src/app/db \
-v /mnt:/mnt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e PUID=1000 \
-e PGID=1000 \
-e FILE_SITE="https://xxx.xxx.xxx/static" \
-e EMBY_SITE="http://172.17.0.1:8096" \
-e EMBY_TOKEN="emby token" \
-e STRM_DIR="/mnt/strm" \
-e REPLACE_STRM_PATH="/Media" \
-e OVERWRITE="false" \
-e NEED_NFO="true" \
-e NEED_IMAGE="false" \
-e JOB_INTERVAL="5" \
-e INIT_QUICK_SCAN="true" \
-e SCAN_DIRS="/Media/Animes|/Media/Movies|/Media/TVShows" \
--name medialibsync \
ilovn/media_library_sync:latest

0x05 答疑

1. 为什么不整理成一个镜像?
   很简单, 专业的工具做专业的事情,同时也利于大家分散部署,比如你的PT下载可能是在欧洲,emby可能在国内或者香港、新加坡等,分散部署可以让工具聚焦自己的主力工作,上传的就专业做上传就行.同理,302可以部署在国内,提升302请求的响应速度.

2. media302用域名的时候,infuse不支持图片302
   这是infuse的bug

3. media302支持strm和本地混合吗?
   不支持,我没这诉求

4. media302会支持plex、jellyfin吗?
   不搞了,没意思

执行命令

通过ssh登录macos后,执行以下命令:

1
2
3
4
5
6

# Enable Screen Sharing
sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.screensharing.plist

# Disable Screen Sharing
sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.screensharing.plist

方案思路

1、通过遍历媒体库资源,全部整理进入数据库;
2、监听115生活事件日志,实现增量数据入库;
3、通过数据库数据快速生成strm和元数据;

特定依赖

之所以没把这个服务打包到media302,主要还是考虑302就专业做302该干的活,数据库的媒体库管理单独开来,这样能实现两个docker应用+emby,实现完整的管理和使用.所以,请把前一篇文章看完.家庭媒体库方案(六):302方案(图片302优化方案,含后端)

动手部署

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

docker pull ilovn/media_library_sync:latest && \
docker run -d \
--restart always \
-v /data/medialibsync/115-cookies.txt:/usr/src/app/115-cookies.txt \
-v /data/medialibsync/db:/usr/src/app/db \
-v /mnt:/mnt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e PUID=1000 \
-e PGID=1000 \
-e FILE_SITE="生成strm的链接服务地址" \
-e EMBY_SITE="emby服务地址,用于通知strm生成,局部扫库" \
-e EMBY_TOKEN="emby token" \
-e STRM_DIR="strm生成的挂载地址" \
-e REPLACE_STRM_PATH="/Media(替换路径)" \
-e OVERWRITE="true是否覆盖已存在的文件" \
-e NEED_NFO="true是否生成nfo" \
-e NEED_IMAGE="false是否生成图片数据" \
-e JOB_INTERVAL="5 任务间隔时间,分钟" \
-e SCAN_DIRS="/Media/Animes|/Media/Movies  预期扫描的路径,|分割" \
--name medialibsync \
ilovn/media_library_sync:latest

问题交流

目前已经基本可用,bug肯定会有,留个联系频道吧,如果有需要的话,戳这里

这次就就直接说明一下更新内容和如何使用吧.

更新内容

• 增加图片302后端服务,但需要提供115网盘的cookie,格式是 UID=...; CID=...; SEID=...,如不提供,也可以指向你自己的后端服务.
• 已重新支持Infuse客户端
• 其他问题优化

参数说明

和之前用法差不多.

1
2
3
4
5
6
7

-e UPSTREAM_HOST="http://172.17.0.1:8096"
-e UPSTREAM_115_SERVER="http://127.0.0.1:8091"
-e EMBY_TOKEN="your emby api token"
-e REPLACE_PATH_1="/mnt/strm"
-e REPLACE_PATH_2="/Media"

-v /data/115/115-cookies.txt:/usr/src/app/115-cookies.txt

简单解释一下,分别是:
1、emby服务地址
2、图片302服务地址,如果你提供了115网盘的cookie,这里保持不变http://127.0.0.1:8091,注意8091端口你可以直接使用,这已经是一个完整的支持302的后端了.
3、emby服务器的api token
4和5、用于图片路径替换的,简单说一下:
假如你的图片原来路径是:
/mnt/strm/Animes/国漫/一念永恒 (2020) {tmdb-107371}/poster.jpg
这个图片在网盘的真实路径是:
/Media/Animes/国漫/一念永恒 (2020) {tmdb-107371}/poster.jpg
图片浏览的路径是:
http://127.0.0.1:8091/Media/Animes/国漫/一念永恒 (2020) {tmdb-107371}/poster.jpg
明白了吧,docker会把你的/mnt/strm替换为/Media,并拼接第二参数你提供的图片服务地址,使用的使用请检查最终能否访问到.
6、把你的115 cookie挂载到docker里.

命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-v /data/115/115-cookies.txt:/usr/src/app/115-cookies.txt \
-v /etc/timezone:/etc/timezone:ro \
-v /etc/localtime:/etc/localtime:ro  \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
-e EMBY_TOKEN="your emby api token" \
-e UPSTREAM_115_SERVER="http://127.0.0.1:8091" \
-e REPLACE_PATH_1="/mnt/strm" \
-e REPLACE_PATH_2="/Media" \
--name media302 \
-p 8090:8090 \
-p 8091:8091 \
ilovn/media302:latest

为啥更新

虽然strm方案没有挂载和缓存的问题,但是媒体库刮削或者已刮削好的资源还是很占用空间,所以你懂的,我现在媒体库规模大概是:

不使用emby刮削,媒体元数据主要包含nfo和海报、分集预览,占用空间24G

使用新的方案后,我只需要保留strm和nfo文件,依旧不使用emby刮削,空间占用:

如何使用

简单解释一下变化

和之前用法差不多,但是因为增加了逻辑处理,需要提供更多参数配置, 参数234任意一个不配置,均不会启用图片302.

1
2
3
4
5

-e UPSTREAM_HOST="http://172.17.0.1:8096"
-e UPSTREAM_115_SERVER="http://172.17.0.1"
-e EMBY_TOKEN="your emby api token"
-e REPLACE_PATH_1="/mnt/strm"
-e REPLACE_PATH_2="/Media"

简单解释一下,分别是:
1、emby服务地址
2、图片302服务地址,这里用alist或者之前家庭媒体库方案(四):虚拟strm及元数据302优化版(待优化)提到的方案
3、emby服务器的api token
4和5、用于图片路径替换的,简单说一下:
假如你的图片原来路径是:
/mnt/strm/Animes/国漫/一念永恒 (2020) {tmdb-107371}/poster.jpg
这个图片在网盘的真实路径是:
/Media/Animes/国漫/一念永恒 (2020) {tmdb-107371}/poster.jpg
图片浏览的路径是:
http://172.17.0.1/Media/Animes/国漫/一念永恒 (2020) {tmdb-107371}/poster.jpg
明白了吧,docker会把你的/mnt/strm替换为/Media,并拼接第二参数你提供的图片服务地址,使用的使用请检查最终能否访问到.

补充说明

针对我个人使用的场景,实际上我的图片全部都不在服务器上存储了,对于图片的命名要求,目前请遵循mp的命名即可,如果有特别的情况,请给我反馈(不一定有精力去复现和修正,我遇到的问题我都会尽快处理掉).

命令

1
2
3
4
5
6
7
8
9
10
11

docker pull ilovn/media302:latest && \
docker run -d \
--restart always \
-e UPSTREAM_HOST="http://172.17.0.1:8096" \
-e EMBY_TOKEN="换成你的emby api token" \
-e UPSTREAM_115_SERVER="图片服务器地址" \
-e REPLACE_PATH_1="本地路径待替换地址,比如/mnt/strm" \
-e REPLACE_PATH_2="网盘被替换地址,比如/Media" \
--name media302 \
-p 8090:8090 \
ilovn/media302:latest

看看效果

存在的问题

1、infuse不支持,分析了infuse接口,不清楚客户端逻辑,无法触发本身没有图片的情况下调用获取图片资源;
2、图片裁剪功能失效,特别是emby客户端展示可能不太美观;vidhub、senplayer、fileball等客户端没问题;

0x00 说明

​ 本次实验并不是从零开始的,相反,很多环节都是原来就存在的节点,我们只是把strm生成这个步骤简化了,还可以跟你原来的emby、media302等方案无缝衔接.

0x01 必要准备

​ 很多人之前可能并没有使用python-115,那么我个人建议,你可以通过学习和了解python-115来快速知道,我们接下来要做的事情.

部署web-302-115-simple

这是开发大佬的高性能简化版302后端,python文件可以在这里找到,拿到这个文件后,可以在你的本地执行验证一下:

1

python3 web_115_302_simple.py

你还可以指定服务在那个端口上启动:

1

python3 web_115_302_simple.py -p 8998

建议在同目录放置115的cookie文件,名字设置为115-cookies.txt就行,里面是字符串格式的Cookie.这样就能在遇到需要验证的时候,自动完成切换.

0x02 部署python-alist

相较于前面的web-302-115-simple的极简部署,python-alist可能更加简单,但是因为依赖的东西可能比较多,我整理成一个脚本,让你看起来只要每次启动这个脚本就行,看起来清爽很多.

先安装一下python-alist:

1

pip3 install -U python-alist

再安装一下fuse相关的应用和依赖:

1
2

sudo apt install libfuse2
pip3 install fusepy

如果是非root用户在跑这些应用,可能还需要修改/etc/fuse.conf,把user_allow_other前的#删掉并保存.

然后,整理一下几个参数备用:

1
2
3
4
5
6
7
8

# alist 服务的地址
ALIST_HOST=http://10.0.0.1:5244
# 用户名
ALIST_USERNAME=alist的用户名
# 密码
ALIST_PASSWORD=alist的密码

# 302的后端服务地址 也就是前面配置的web-302-115-simple的服务地址

0x03 写个简单的脚本

脚本就叫alist-fise.sh,把你准备好的参数,放到我下面的脚本内容中,并保存到alist-fise.sh:

注意:

• –base-dir 是你在alist里面挂载的115的路径,不一定是/115,根据需要修改;
• –strm-make 前面配置的web-302-115-simple的服务地址
• –open-file 前面配置的web-302-115-simple的服务地址
• 最后一行的–不要删,后面跟着的是你要挂载的目标目录,目录必须存在并且文件夹内是空的

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# alist 服务的地址
ALIST_HOST=http://10.0.8.3:5244
# 用户名
ALIST_USERNAME=alist的用户名
# 密码
ALIST_PASSWORD=alist的密码

python-alist fuse \
    --origin "$ALIST_HOST" \
    --username "$ALIST_USERNAME" \
    --password "$ALIST_PASSWORD" \
    --base-dir '/115' \
    --refresh \
    --strm-predicate-type expr \
    --strm-predicate '(
        path.media_type.startswith(("video/", "audio/")) and 
        path.suffix.lower() != ".ass"
    )' \
    --predicate-type expr \
    --predicate '(
        path.is_dir() or 
        path.media_type.startswith("image/") or 
        path.suffix.lower() in (".nfo", ".ass", ".ssa", ".srt", ".idx", ".sub", ".txt", ".vtt", ".smi")
        )' \
    --strm-make-type fstring \
    --strm-make '前面配置的web-302-115-simple的服务地址/{path.relative_to("/115")}' \
    --open-file-type fstring \
    --open-file '前面配置的web-302-115-simple的服务地址/{path.relative_to("/115")}' \
    -- /mnt/alist

然后跑起来吧:

1

sh alist-fuse.sh

1
2
3
4
5
6

ubuntu@VM-0-6-ubuntu:~$ sh alist-fise.sh 

        👋 Welcome to use alist fuse 👏

    mounted at: '/mnt/alist'
    FUSE options: {'mountpoint': '/mnt/alist', 'allow_other': True, 'foreground': True, 'max_readahead': 0, 'noauto_cache': True, 'ro': True}

检查一下你的挂载目录,是不是文件都来了,是不是媒体文件都变成了同名的strm文件,剩下的就是去emby里面添加对应的媒体库,指向这些目录吧,如果原来你是同结构的strm,那么还可以清空原目录,直接挂载过去,emby都不需要重新设置.

0x04 问题待优化

​ 目前媒体元数据的图片这些也是走302连接,但是因为fuse2的问题,可能存在图片显示不完整问题,开发大佬表示已经在优化了,后面解决了如果部署步骤有更新我会说明.