Linux 企业级部署：systemd、远程访问与并发

# systemd 覆盖片段：只写你要加的几行，不动官方原文件。
#
# 生成方式（不要手动创建文件，让 systemd 自己建目录）：
#   systemctl edit ollama
# 它会打开编辑器，把下面内容粘进去保存，实际落在：
#   /etc/systemd/system/ollama.service.d/override.conf
#
# 相比直接改 /etc/systemd/system/ollama.service 的好处：
#   升级 Ollama 时官方模板被覆盖，你的这几行仍然在。
#
# 保存之后照样要走完四步闭环：
#   systemctl daemon-reload && systemctl restart ollama
#   然后读 /proc/<PID>/environ 确认变量真的进去了

[Service]
# 模型放数据盘。注意：改这个值之后，已经拉过的模型不会自动搬家。
Environment="OLLAMA_MODELS=/data/ollama/models"

# 生产建议保持回环，对外由 Nginx 网关代理。
# 只有在没有网关、纯内网联调时才改成 0.0.0.0。
Environment="OLLAMA_HOST=127.0.0.1:11434"

# 工作时间基本一直有人用，留久一点，省掉反复加载的几十秒。
Environment="OLLAMA_KEEP_ALIVE=30m"

# 并发路数用 concurrency_plan.py 算出来，别拍脑袋。
# 显存够不代表能开很多路 —— 算力会先饱和。
Environment="OLLAMA_NUM_PARALLEL=4"

# 单模型服务设成 1，别让第二个模型来分显存。
Environment="OLLAMA_MAX_LOADED_MODELS=1"

# 队列不宜过长：排到的时候请求早该超时了，不如直接失败让客户端重试。
Environment="OLLAMA_MAX_QUEUE=256"

Environment="OLLAMA_CONTEXT_LENGTH=4096"

"""并发规划：这块卡、这个模型，最多能开几路并发。

上一讲讲过「先定并发数，再倒推模型尺寸」，这里给出具体算法。

估算口径：
    总占用 ≈ 模型权重 + 并发数 × 单路 KV 缓存 + 运行时开销
    权重是所有并发请求**共用的一份**，不随并发增长；
    KV 缓存是**每路一份**，且随上下文长度线性上涨 —— 这才是并发的真实代价。

单路 KV 缓存的粗略估法：
    KV ≈ 上下文长度 × 每 token 的 KV 字节数
    每 token 的 KV 字节数随模型层数和隐藏维度变化，
    这里按常见 7B~32B 稠密模型的经验值给区间，不做精确计算。

用法：
    python3 concurrency_plan.py --vram 24 --params 14
    python3 concurrency_plan.py --vram 24 --params 14 --ctx 8192
"""
import argparse
import sys

BYTES_PER_PARAM = {"FP16": 2.0, "Q8": 1.0, "Q4": 0.55}

# 每 token 的 KV 缓存字节数（经验区间，随参数量增大而增大）
# 取值偏保守，宁可估多不估少 —— 估少了上线就 OOM。
def kv_bytes_per_token(params_b):
    if params_b <= 2:
        return 60 * 1024        # 约 60KB
    if params_b <= 8:
        return 130 * 1024
    if params_b <= 16:
        return 200 * 1024
    return 320 * 1024


def plan(vram_gb, params_b, quant, ctx, reserve_ratio=0.2):
    gib = 1024 ** 3
    weights = params_b * 1e9 * BYTES_PER_PARAM[quant] / gib
    kv_one = kv_bytes_per_token(params_b) * ctx / gib
    # 运行时开销：激活值、中间结果等，按权重的一成估
    runtime = weights * 0.1
    # 留给系统和显存碎片的余量
    usable = vram_gb * (1 - reserve_ratio)

    budget = usable - weights - runtime
    max_parallel = int(budget // kv_one) if kv_one > 0 else 0

    return {
        "显存总量": vram_gb,
        "可用预算": usable,
        "模型权重": weights,
        "运行时开销": runtime,
        "单路 KV 缓存": kv_one,
        "理论最大并发": max_parallel,
    }


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--vram", type=float, required=True, help="显存大小，GB")
    ap.add_argument("--params", type=float, required=True, help="参数量，单位 B")
    ap.add_argument("--quant", default="Q4", choices=list(BYTES_PER_PARAM))
    ap.add_argument("--ctx", type=int, default=4096, help="上下文长度 num_ctx")
    ap.add_argument("--reserve", type=float, default=0.2, help="预留比例，默认两成")
    args = ap.parse_args()

    r = plan(args.vram, args.params, args.quant, args.ctx, args.reserve)

    print("=" * 56)
    print("配置：%.0fGB 显存 · %gB 模型 · %s 量化 · 上下文 %d"
          % (args.vram, args.params, args.quant, args.ctx))
    print("=" * 56)
    print("  显存总量        %6.1f GB" % r["显存总量"])
    print("  预留后可用      %6.1f GB   （留了 %.0f%%）"
          % (r["可用预算"], args.reserve * 100))
    print("  模型权重        %6.1f GB   （所有并发共用一份）" % r["模型权重"])
    print("  运行时开销      %6.1f GB" % r["运行时开销"])
    print("  单路 KV 缓存    %6.2f GB   （每路一份，随 ctx 线性上涨）"
          % r["单路 KV 缓存"])
    print("-" * 56)

    n = r["理论最大并发"]
    if n <= 0:
        print("结论：这块卡装不下这个配置。")
        print("      降量化档、换更小的模型，或者把 num_ctx 调小。")
        return 0

    # 关键：显存只是两个约束中的一个。
    # 即使显存还剩很多，并发路数一多，GPU 算力也会先饱和：
    # 总吞吐基本不再涨，而每一路的生成速度成比例变慢。
    # 对交互式问答来说，单路掍到 15 token/s 以下就已经憋得慌了，
    # 所以实际可用并发通常远低于显存算出来的那个数。
    COMPUTE_CAP = 4        # 单卡交互式服务的经验上限
    vram_safe = max(1, n - 1)          # 留一路给突发，避免跑满顶掉显存
    safe = min(vram_safe, COMPUTE_CAP)

    print("显存约束下的最大并发：%d 路" % n)
    print("算力约束下的经验上限：%d 路（交互式问答，单卡）" % COMPUTE_CAP)
    if vram_safe > COMPUTE_CAP:
        print("  → 显存不是瓶颈，算力是。再往上开只会让每一路都变慢。")
        print("  → 富余的显存更值得拿去调大 num_ctx，或者换更大的模型。")
    print("建议配置：OLLAMA_NUM_PARALLEL=%d" % safe)
    print()
    print("配套建议：")
    print("  OLLAMA_MAX_LOADED_MODELS=1   单模型服务，别让第二个模型分显存")
    print("  OLLAMA_CONTEXT_LENGTH=%d" % args.ctx)
    print()
    print("⚠️  这是估算，不是验收标准。")
    print("    配完必须压测验证：bench_local.py --concurrency %d" % safe)
    print("    压测时盯住 ollama ps 的 PROCESSOR 列，出现 CPU 就是溢出了。")
    return 0


if __name__ == "__main__":
    sys.exit(main())

[Unit]
Description=Ollama Service
# 等网络真正可用再启动，否则开机时拉模型会失败
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/bin/ollama serve
User=root
Group=root
# 进程挂了自动拉起，3 秒后重试——私有化服务必须配，否则半夜挂了没人知道
Restart=always
RestartSec=3

# ---- 模型存放位置：默认在系统盘，模型动辄几十 GB，务必挪到数据盘 ----
Environment="OLLAMA_MODELS=/data/ollama/models"

# ---- 监听地址：默认只听 127.0.0.1，别的机器连不上 ----
# 改成 0.0.0.0 才能被内网访问。注意：这一步只是「开门」，不带任何鉴权
Environment="OLLAMA_HOST=0.0.0.0:11434"

# ---- 允许的浏览器来源，给 Web 客户端用 ----
Environment="OLLAMA_ORIGINS=*"

# ---- 内存驻留时长：默认 5m。高频服务设长一点，省掉反复加载的几十秒 ----
Environment="OLLAMA_KEEP_ALIVE=30m"

# ---- 并发控制：显存有限时这两个值决定服务会不会被打爆 ----
# 一个模型同时处理几个请求，默认 1；显存需求随它成倍上涨
Environment="OLLAMA_NUM_PARALLEL=2"
# 同时加载几个模型，默认是 3×GPU 数
Environment="OLLAMA_MAX_LOADED_MODELS=1"
# 忙不过来时的排队上限，默认 512；超出后服务端直接返回 503
Environment="OLLAMA_MAX_QUEUE=256"

# ---- 默认上下文长度，默认 4096 ----
Environment="OLLAMA_CONTEXT_LENGTH=4096"

[Install]
WantedBy=default.target

# Nginx 网关：Ollama 自己没有任何鉴权，所有访问控制都做在这一层。
#
# 落地方式：
#   1. 把这个文件放到 /etc/nginx/conf.d/ollama-gateway.conf
#   2. Ollama 只监听回环：OLLAMA_HOST=127.0.0.1:11434
#   3. nginx -t 语法检查通过后再 systemctl reload nginx
#
# 口令文件生成（不要把明文口令写进任何配置文件）：
#   htpasswd -c /etc/nginx/ollama.htpasswd 你的用户名

# 按来源 IP 限速：每秒 5 个请求，突发 10 个
limit_req_zone $binary_remote_addr zone=ollama_rl:10m rate=5r/s;

upstream ollama_backend {
    # Ollama 只在本机回环监听，外部进不来，必须经过这个网关
    server 127.0.0.1:11434;
    keepalive 16;
}

server {
    listen 443 ssl;
    server_name ai.example.com;   # 改成你自己的内网域名

    ssl_certificate     /etc/nginx/ssl/ai.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/ai.example.com.key;

    # 单次请求体上限：多模态要传 base64 图片，默认 1m 会被截断
    client_max_body_size 32m;

    access_log /var/log/nginx/ollama-access.log;
    error_log  /var/log/nginx/ollama-error.log warn;

    location / {
        # ---- 第一道：账号口令 ----
        auth_basic           "Ollama Private";
        auth_basic_user_file /etc/nginx/ollama.htpasswd;

        # ---- 第二道：限速 ----
        limit_req zone=ollama_rl burst=10 nodelay;

        # ---- 第三道：只放行需要的接口，管理类接口一律拒绝 ----
        # 不加这一条的话，任何人都能调 /api/delete 把模型删光
        location ~ ^/api/(delete|pull|push|create|copy) {
            deny all;
        }

        proxy_pass http://ollama_backend;
        # Ollama 会校验 Host 头，必须改写成它自己认的值
        proxy_set_header Host localhost:11434;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;

        # ---- 流式返回必须关缓冲，否则前端要等全部生成完才看见字 ----
        proxy_buffering off;
        proxy_cache off;

        # ---- 大模型首个 token 可能等几十秒，超时要放宽 ----
        proxy_connect_timeout 10s;
        proxy_send_timeout    600s;
        proxy_read_timeout    600s;
    }
}

#!/bin/bash
# 排障顺序：从「服务在不在」一路查到「模型答不答得出」，一层不通就停在那一层。
# 出问题时按顺序跑一遍，不要跳步——跳步会把「没起服务」误判成「模型坏了」。
set -uo pipefail

HOST="${OLLAMA_HOST_ADDR:-127.0.0.1}"
PORT="${OLLAMA_PORT:-11434}"
MODEL="${MODEL:-qwen2:1.5b}"

echo "===== ① 进程与服务状态 ====="
systemctl is-active ollama || echo "服务不是 active，先看第 ② 步日志"
systemctl status ollama --no-pager | head -8

echo
echo "===== ② 服务日志（最近 30 行） ====="
# 启动失败的真正原因几乎都在这里：端口被占、模型目录没权限、显卡驱动不认
journalctl -u ollama -n 30 --no-pager

echo
echo "===== ③ 端口有没有在监听 ====="
# 只看到 127.0.0.1:11434 说明没开远程；要被别的机器访问必须是 0.0.0.0
ss -lntp | grep "$PORT" || echo "端口没监听"

echo
echo "===== ④ 环境变量是否真的生效 ====="
# 注意：这里看的是进程实际拿到的环境，比看配置文件可靠
# 只改了 service 文件却没 daemon-reload + restart，这里就会露馅
PID=$(systemctl show -p MainPID --value ollama)
if [ "$PID" != "0" ] && [ -r "/proc/$PID/environ" ]; then
  tr '\0' '\n' < "/proc/$PID/environ" | grep '^OLLAMA_' || echo "没有任何 OLLAMA_ 变量"
else
  echo "拿不到主进程 PID，服务可能没起来"
fi

echo
echo "===== ⑤ 本机能不能连通 ====="
curl -s -m 5 "http://${HOST}:${PORT}/api/version" || echo "本机都连不上，问题在服务侧"

echo
echo "===== ⑥ 防火墙有没有放行 ====="
firewall-cmd --list-ports 2>/dev/null || echo "没装 firewalld 或没启用"

echo
echo "===== ⑦ 模型在不在、占的是 GPU 还是 CPU ====="
ollama list
ollama ps

echo
echo "===== ⑧ 真发一次推理 ====="
# 前七步全通但这步不通，才轮得到怀疑模型本身
curl -s -m 120 "http://${HOST}:${PORT}/api/chat" \
  -d "{\"model\":\"${MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复两个字：正常\"}],\"stream\":false}"
echo

#!/bin/bash
# 网关冒烟测试：验证「走网关能通」和「直连 11434 不通」两条同时成立。
#
# 为什么必须两条都测：
#   只测第一条，很可能网关配好了、11434 也还在内网裸奔，
#   任何人绕过网关直连就能删模型 —— 网关形同虚设。
#
# 用法（在一台**不是** Ollama 服务器的机器上跑，才有意义）：
#   GATEWAY=https://ai.example.com OLLAMA_DIRECT=192.168.1.10:11434 \
#   AUTH_USER=alice bash gateway_smoke_test.sh
#
# 口令通过环境变量传入，不要写进命令行参数（会留在 history 里）。
set -uo pipefail

GATEWAY="${GATEWAY:-https://ai.example.com}"
OLLAMA_DIRECT="${OLLAMA_DIRECT:-192.168.1.10:11434}"
AUTH_USER="${AUTH_USER:-}"
# 口令从环境变量读；没给就走交互式输入，避免出现在进程列表里
if [ -z "${AUTH_PASS:-}" ] && [ -n "$AUTH_USER" ]; then
  read -rsp "输入 $AUTH_USER 的口令：" AUTH_PASS
  echo
fi

PASS=0
FAIL=0

check() {
  local name="$1" expect="$2" actual="$3"
  if [ "$expect" = "$actual" ]; then
    echo "  ✅ $name  （期望 $expect，实际 $actual）"
    PASS=$((PASS + 1))
  else
    echo "  ❌ $name  （期望 $expect，实际 $actual）"
    FAIL=$((FAIL + 1))
  fi
}

# 只取 HTTP 状态码，不打印响应体
code() {
  curl -s -o /dev/null -w '%{http_code}' -m 15 "$@" 2>/dev/null || echo "000"
}

echo "===== ① 直连 11434 应该连不上 ====="
# 这是最关键的一条。生产上 Ollama 应该只监听 127.0.0.1，
# 从别的机器直连必须失败（000 表示连接被拒或超时）。
DIRECT=$(code "http://${OLLAMA_DIRECT}/api/version")
check "直连 /api/version 被拒" "000" "$DIRECT"

echo
echo "===== ② 不带口令走网关应该被挡 ====="
NOAUTH=$(code "${GATEWAY}/api/version")
check "无口令请求返回 401" "401" "$NOAUTH"

echo
echo "===== ③ 带正确口令走网关应该通 ====="
if [ -n "$AUTH_USER" ]; then
  OK=$(code -u "${AUTH_USER}:${AUTH_PASS}" "${GATEWAY}/api/version")
  check "带口令请求返回 200" "200" "$OK"
else
  echo "  ⏭  没给 AUTH_USER，跳过"
fi

echo
echo "===== ④ 管理类接口即使带口令也应该被拒 ====="
# 网关的接口白名单是挡住最严重事故的那一层：
# /api/delete 能把线上模型删光。
if [ -n "$AUTH_USER" ]; then
  # 故意发一个不存在的模型名，就算白名单失效也删不掉真东西
  DEL=$(code -u "${AUTH_USER}:${AUTH_PASS}" -X DELETE \
        -H 'Content-Type: application/json' \
        -d '{"name":"__smoke_test_not_exist__"}' \
        "${GATEWAY}/api/delete")
  check "/api/delete 被网关拒绝（403）" "403" "$DEL"

  PULL=$(code -u "${AUTH_USER}:${AUTH_PASS}" -X POST \
         -H 'Content-Type: application/json' \
         -d '{"name":"__smoke_test_not_exist__"}' \
         "${GATEWAY}/api/pull")
  check "/api/pull 被网关拒绝（403）" "403" "$PULL"
else
  echo "  ⏭  没给 AUTH_USER，跳过"
fi

echo
echo "============================================"
echo "通过 $PASS 项，失败 $FAIL 项"
if [ "$FAIL" -gt 0 ]; then
  echo "⚠️  有失败项，网关还没配到位，不要对外放行。"
  exit 1
fi
echo "✅ 两条都成立：走网关能通、直连不通。"

"""健康巡检：周期性探活，把「服务悄悄坏了」变成「有人知道」。

systemd 的 Restart=always 只能解决「进程死了」这一种故障。
更常见也更难发现的是下面这几种 —— 进程活着，服务却已经不可用：

    · 模型溢出到 CPU，速度掉到几 token/s，用户以为卡死
    · 显存被别的进程占走，模型加载失败但服务端口还在
    · 磁盘满了，写不进日志和模型
    · 响应时间越来越长，其实是并发排队

这个脚本每隔一段时间做一次完整探测，把结果按行写进日志。
它**只观测、只告警，不自动重启** —— 自动重启在故障没定位前
往往只是把问题掩盖掉，变成周期性抖动。

用法：
    python3 health_watch.py                       # 前台跑，Ctrl-C 结束
    python3 health_watch.py --interval 300 --log /var/log/ollama-health.log
    # 想让它常驻，再写一个 systemd 服务托管它，别用 nohup

退出码：0 正常结束；1 启动参数有问题。
"""
import argparse
import json
import os
import sys
import time
import urllib.error
import urllib.request
from datetime import datetime

BASE = os.environ.get("OLLAMA_BASE", "http://127.0.0.1:11434").rstrip("/")


def now():
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")


def http_json(path, payload=None, timeout=20):
    url = BASE + path
    if payload is None:
        req = urllib.request.Request(url)
    else:
        req = urllib.request.Request(
            url, data=json.dumps(payload).encode("utf-8"),
            headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        return json.loads(resp.read().decode("utf-8"))


def probe(model, timeout):
    """做一轮完整探测，返回 (级别, 一行摘要)。

    级别：OK / WARN / CRIT
    分级依据是「用户感受得到吗」：
        CRIT  服务不可用，必须立刻处理
        WARN  还能用但已经不正常，会演变成故障
        OK    正常
    """
    # ---- ① 服务活着吗 ----
    try:
        ver = http_json("/api/version", timeout=10).get("version", "?")
    except (urllib.error.URLError, TimeoutError) as exc:
        return "CRIT", "服务不可达：%s" % exc

    # ---- ② 模型在显存里吗、占的是 GPU 还是 CPU ----
    processor = "未加载"
    try:
        running = http_json("/api/ps", timeout=10).get("models", [])
        for m in running:
            if m.get("name") == model:
                total = m.get("size", 0)
                vram = m.get("size_vram", 0)
                if total <= 0:
                    processor = "未知"
                elif vram >= total:
                    processor = "100% GPU"
                elif vram <= 0:
                    processor = "100% CPU"
                else:
                    processor = "%d%% GPU" % int(vram * 100 / total)
                break
    except Exception as exc:
        return "WARN", "版本 %s，但读 /api/ps 失败：%s" % (ver, exc)

    # ---- ③ 真发一次推理，测端到端延迟 ----
    # 前两步全通、这一步不通，才说明问题出在模型本身
    t0 = time.time()
    try:
        data = http_json("/api/chat", {
            "model": model,
            "messages": [{"role": "user", "content": "只回复两个字：正常"}],
            "stream": False,
            # 探活请求不要把模型顶进内存太久，也不要把别人的挤出去
            "keep_alive": "5m",
            "options": {"temperature": 0, "num_predict": 8},
        }, timeout=timeout)
    except (urllib.error.URLError, TimeoutError) as exc:
        return "CRIT", "版本 %s，推理失败：%s" % (ver, exc)

    wall = time.time() - t0
    tokens = data.get("eval_count", 0)
    eval_s = data.get("eval_duration", 0) / 1e9
    tps = tokens / eval_s if eval_s else 0

    summary = ("版本 %s | %s | 端到端 %.1fs | %.1f token/s"
               % (ver, processor, wall, tps))

    # ---- 分级 ----
    if "CPU" in processor and processor != "100% GPU":
        # 溢出到 CPU 是最典型的「进程活着但服务已经不可用」
        return "WARN", summary + " | 已溢出到 CPU，速度会明显下降"
    if tps and tps < 5:
        return "WARN", summary + " | 生成速度过低，检查是否在排队或溢出"
    if wall > 30:
        return "WARN", summary + " | 端到端延迟过高"
    return "OK", summary


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--model", default=os.environ.get("OLLAMA_MODEL", "qwen2:1.5b"))
    ap.add_argument("--interval", type=int, default=300, help="探测间隔秒数")
    ap.add_argument("--timeout", type=int, default=120, help="单次推理超时")
    ap.add_argument("--log", default="", help="日志文件；不给就打印到标准输出")
    ap.add_argument("--once", action="store_true", help="只探一次就退出，适合放 cron")
    args = ap.parse_args()

    out = open(args.log, "a", encoding="utf-8") if args.log else sys.stdout

    def emit(level, msg):
        line = "[%s] %-4s %s" % (now(), level, msg)
        print(line, file=out)
        out.flush()      # 每行都刷，进程被杀也不丢已经写的记录

    emit("INFO", "开始巡检 %s，模型 %s，间隔 %ds"
         % (BASE, args.model, args.interval))

    consecutive_bad = 0
    try:
        while True:
            level, msg = probe(args.model, args.timeout)
            emit(level, msg)

            if level == "OK":
                consecutive_bad = 0
            else:
                consecutive_bad += 1
                # 连续异常才升级告警：单次抖动不值得半夜叫醒人
                if consecutive_bad >= 3:
                    emit("ALERT", "连续 %d 次异常，需要人工介入" % consecutive_bad)

            if args.once:
                break
            time.sleep(args.interval)
    except KeyboardInterrupt:
        emit("INFO", "手动停止")
    finally:
        if args.log:
            out.close()
    return 0


if __name__ == "__main__":
    sys.exit(main())