<![CDATA[私有化AI项目踩坑清单：GPU、网络、证书、日志、备份和升级]]>私有化 AI 项目最容易被低估的部分，不是模型本身，而是模型周围的基础设施。演示环境里，一台机器、一块显卡、一个容器、一条命令就能跑起来；真实交付时，问题会从四面八方冒出来：驱动和 CUDA 版本不匹配，容器看不到 GPU，内网 DNS 解析错，反向代理拿不到证书，日志把磁盘写满，备份从来没有恢复过，升级后模型服务启动但吞吐跌了一半。很多项目不是败在“模型不够聪明”，而是败在这些基础工程没有被当成产品的一部分。

私有化 AI 的本质是把模型能力放进客户或团队自己的运行边界里。这个边界里可能有离线网络、国产化设备、老旧虚拟化平台、严格防火墙、自签证书、混合云线路、共享 GPU、单机 Docker Compose、小型 Kubernetes、内部对象存储、审计要求和人工运维流程。每个环节都可能让原本在云厂商托管平台上很顺的体验变得复杂。要把项目做成生产级应用，必须把 GPU、网络、证书、日志、备份和升级当作同等重要的交付项，而不是上线前临时补配置。

下面这份清单面向真正要落地私有化 AI 的团队。它不讨论概念上的“私有化好不好”，而是聚焦工程现场最常见、最耗时间、最容易造成返工的问题。每一类坑都可以提前规避，只要在设计、部署、验收和运维阶段把检查项写清楚。

一、先分清交付形态：单机、Compose、Kubernetes和混合部署

私有化 AI 项目第一步不是选模型，而是确认运行形态。单机部署、Docker Compose、多节点 Kubernetes、GPU 裸机加网关、云边混合部署，它们的风险完全不同。单机部署简单，但扩容、故障迁移和资源隔离弱；Compose 适合中小规模和快速交付，但跨主机调度能力有限；Kubernetes 适合多租户、多服务和长期运维，但复杂度显著上升；混合部署能兼顾内部数据和外部模型能力，但网络、证书和审计会更难。

很多踩坑来自“用演示形态承诺生产能力”。演示时在一台 GPU 机器上跑 Ollama、vLLM 或 TGI，再接一个 Web UI，就能展示对话效果。到了生产，用户会问：多个人同时请求怎么办，模型热更新怎么办，日志保留多久，机器宕机怎么办，证书谁续期，备份能不能恢复，升级失败如何回滚，内网域名怎么解析，审计能不能查到某次调用。演示形态如果没有这些答案，就不能直接当生产方案。

交付形态还影响责任边界。使用 Docker Compose，很多问题落在宿主机：NVIDIA 驱动、Container Toolkit、Docker 日志、端口暴露、挂载目录、系统服务重启。使用 Kubernetes，问题会变成节点标签、device plugin、GPU Operator、StorageClass、Ingress、Service DNS、Pod 日志采集、Helm 升级和集群版本偏移。两者不是谁更高级，而是适用场景不同。小团队没有 Kubernetes 运维能力，却强行上集群，会把问题从应用部署变成平台运维；大型组织只靠单机脚本，又会在权限、审计和扩容上卡住。

一个稳妥的做法是先写交付边界表：部署节点数量、GPU 型号、操作系统、容器运行时、网络入口、证书来源、数据存储位置、日志后端、备份目标、升级方式、回滚方式、验收指标。边界不清时，不要急着下载模型。私有化项目真正费时间的，往往正是这些“模型之外”的部分。

二、GPU第一坑：显卡存在，不代表容器能用

GPU 问题最常见的误判是：宿主机 nvidia-smi 能看到显卡，所以 AI 服务就能用 GPU。实际链路更长。宿主机需要正确安装 NVIDIA 驱动，驱动要和 CUDA 运行需求兼容；容器运行时需要 NVIDIA Container Toolkit；Docker 或 containerd 要正确配置 runtime；容器启动参数要暴露 GPU；应用框架还要能识别对应 CUDA、ROCm、Metal 或 CPU 后端。任何一环错，最终都可能退回 CPU 或直接启动失败。

NVIDIA Container Toolkit 官方文档明确把容器 runtime 配置作为 GPU 容器化的关键步骤。Docker 场景里，常见检查不是只跑宿主机 nvidia-smi，还要跑一个 CUDA 容器验证容器内是否能看到 GPU。Ollama 官方 Docker 文档也给出 --gpus=all 的运行方式。对于 vLLM、TGI、Triton 这类服务，同样要在容器内确认 CUDA 可见、模型加载到显存、推理时 GPU 利用率变化，而不是只看服务端口返回 200。

第二个坑是驱动和 CUDA 版本。CUDA Toolkit、驱动、PyTorch、vLLM 镜像、模型量化格式之间存在兼容关系。NVIDIA CUDA Compatibility 文档说明了驱动和 CUDA 运行时的兼容逻辑，但项目现场经常出现“镜像里 CUDA 很新，宿主机驱动太旧”的问题。表现可能是容器启动时报 driver insufficient，也可能是模型加载到一半报动态库错误。解决这类问题不能靠反复换镜像标签碰运气，应先列出宿主机驱动版本、镜像 CUDA 版本、框架版本和 GPU 架构，再按官方兼容表确认。

第三个坑是显存估算过于乐观。模型参数占用只是基础，推理还需要 KV cache、batch、并发请求、上下文长度和框架开销。一个模型“能加载”不代表能生产服务。长上下文、多并发和流式输出都会放大显存压力。vLLM 的核心优势之一是高效管理 KV cache 和连续批处理，但这并不意味着显存无限。项目验收要测实际并发、首 token 延迟、平均输出速度、显存峰值和 OOM 行为。

第四个坑是多 GPU 使用方式不清。多张卡可以用于张量并行、流水并行、数据并行、不同模型拆分部署，或者给不同服务独占。不同框架支持不同策略。把多张卡暴露给一个容器，不等于模型会自动均衡使用；把一个大模型强塞到多卡，也不等于吞吐一定提升。验收时要明确每张卡的用途、显存占用、故障影响和调度策略。

第五个坑是虚拟化和直通。很多私有化环境跑在 Proxmox、VMware、云桌面或企业虚拟化平台上，GPU passthrough、MIG、vGPU、驱动授权、IOMMU、容器 runtime 之间叠加复杂。现场排障要分层：物理机看到 GPU，虚拟机看到 GPU，虚拟机驱动正常，容器看到 GPU，应用使用 GPU。不要跳层排查。

三、Kubernetes GPU坑：调度成功不等于资源可用

Kubernetes 环境里，GPU 不是普通 CPU 资源。上游 Kubernetes 需要设备插件把 GPU 暴露成可调度资源，NVIDIA 官方 k8s-device-plugin 就是这一层的常见实现。NVIDIA GPU Operator 则更进一步，把驱动、Container Toolkit、device plugin、GPU Feature Discovery、DCGM Exporter 等组件纳入集群化管理。选择手工装插件还是用 Operator，要看集群权限、节点一致性和运维能力。

第一类坑是节点准备不完整。device plugin README 明确假设驱动和 NVIDIA Container Toolkit 已经安装。很多团队只部署 DaemonSet，结果 Pod 申请 nvidia.com/gpu 后仍然跑不起来，因为节点底层还没准备好。正确检查顺序是：节点驱动、容器 runtime、device plugin Pod 状态、节点 allocatable 里是否出现 GPU、测试 Pod 是否能运行 CUDA。

第二类坑是调度和实际使用脱节。Pod 成功调度到 GPU 节点，只说明 Kubernetes 分配了资源，不说明应用真的用上 GPU。容器镜像里 CUDA 库、模型服务参数、环境变量、权限和启动命令仍然可能出错。验收要进入 Pod 或看应用指标，确认推理进程实际占用显存。

第三类坑是共享策略。NVIDIA device plugin 支持一些共享访问配置，MIG 也能把部分 GPU 切成实例。共享能提高利用率，但会带来隔离、性能波动和排障难度。私有化 AI 项目如果面向多个部门或多个模型，必须提前决定是独占、时间共享、MIG 切分还是按服务拆卡。没有策略时，很容易出现某个测试任务占满显存，生产问答突然 OOM。

第四类坑是监控缺失。GPU 节点不是只看 Pod Ready。要看显存、GPU 利用率、温度、功耗、ECC 错误、驱动错误、模型请求队列、批处理状态和推理延迟。NVIDIA Triton、vLLM、TGI 都提供 Prometheus 指标入口或相关指标，DCGM Exporter 也常用于 GPU 层监控。没有指标，GPU 问题只能靠用户抱怨“变慢了”才发现。

第五类坑是升级顺序。Kubernetes、驱动、GPU Operator、device plugin、container runtime、模型镜像都可能互相影响。集群升级前要读 Kubernetes version skew policy，也要读 GPU Operator 或插件版本说明。不要在同一个窗口同时升级驱动、集群和模型服务，否则出了问题很难定位。

四、模型服务坑：启动成功不等于可服务

模型服务启动并监听端口，只是最低层的活性检查。生产可服务还要看并发、排队、上下文长度、流式响应、超时、取消请求、模型热切换、错误码、指标和限流。很多私有化项目验收只做一次 curl，返回一句话就算成功，真正上线后才发现用户一多就卡死。

vLLM 文档说明它通过 OpenAI 兼容 API 服务暴露 /metrics，用于监控系统健康。TGI 文档也提供 Prometheus 指标，包括批处理大小、prefill 和 decode 时长等。Triton 默认也有 Prometheus metrics。模型服务验收应该把这些指标纳入看板：请求数、失败数、排队时间、首 token 延迟、tokens per second、显存使用、KV cache 使用、批大小、重试次数。没有这些指标，无法判断瓶颈在模型、GPU、网络、网关还是客户端。

第二个坑是超时设置不匹配。长回答可能需要几十秒甚至更久，反向代理、网关、浏览器、后端、模型服务各层都有 timeout。如果模型还在生成，网关先断开，用户看到的就是失败；如果客户端断开后服务端不取消推理，GPU 仍然会浪费计算。生产链路要统一超时策略，并支持取消请求。

第三个坑是上下文长度和并发互相挤压。模型支持 32K 上下文，不代表所有用户都能同时跑 32K。上下文越长，prefill 越重，KV cache 越大。私有化项目应该给不同入口设置默认上限：普通问答、知识库问答、长文生成、代码分析、批量任务可以有不同限制。否则一个超长请求就可能拖慢全体用户。

第四个坑是镜像标签使用 latest。私有化环境最怕不可复现。今天拉到的镜像和下周拉到的镜像不同，出现问题很难回滚。生产部署应固定镜像 digest 或明确版本标签，模型文件也要有版本、校验和和来源记录。升级新版本时先灰度验证，再切换流量。

第五个坑是模型文件管理混乱。模型权重很大，下载慢，权限敏感，磁盘占用高。多个服务重复下载同一模型会浪费空间；模型放在容器层会导致镜像过大；模型挂载目录如果没有备份和校验，迁移时容易缺文件。应明确模型仓库、缓存目录、挂载方式、校验和、清理策略和访问权限。

五、网络坑：容器名、服务名、域名和入口不是一回事

私有化环境网络问题比公网 SaaS 更复杂。Docker Compose 里，服务默认加入同一个网络，可以通过 service name 互相发现；Docker 文档也说明配置变更后容器 IP 可能变化，但服务名保持可解析。Kubernetes 里，Service 和 Pod DNS 有自己的规则，跨命名空间、Headless Service、Ingress、NodePort、LoadBalancer 都会影响访问路径。很多问题来自把这些层混在一起。

第一类坑是用 IP 写死服务地址。容器重建、Pod 重调度、节点迁移后 IP 会变。Compose 内部应优先用服务名，Kubernetes 内部应优先用 Service DNS。只有外部入口才使用稳定域名或负载均衡地址。写死 IP 看似简单，后期排障和迁移成本很高。

第二类坑是把内部地址暴露给用户。模型服务、向量库、数据库、对象存储、管理后台不应全部直接暴露。用户入口应该经过统一网关或反向代理，内部服务只在受控网络里互通。否则一次配置错误就可能把未认证接口暴露到内网甚至公网。

第三类坑是 DNS 解析路径不一致。服务器上能解析，不代表容器里能解析；Pod 里能解析，不代表浏览器能解析；内网 DNS 能解析，不代表 Let's Encrypt 能验证。私有化项目要明确 DNS 分层：用户浏览器解析的域名、反向代理解析的上游、容器网络内解析的服务名、证书验证方看到的公网或 DNS TXT 记录。很多证书和回调问题，本质都是 DNS 视角不同。

第四类坑是代理和离线环境。私有化交付常常不能直接访问外网，拉镜像、下载模型、申请证书、访问外部 API 都会失败。离线包、私有镜像仓库、模型离线分发、证书离线或 DNS-01 自动化、软件源镜像，这些必须提前准备。不要到客户现场再发现 docker pull 和模型下载都被拦。

第五类坑是 WebSocket、SSE 和流式响应。AI 对话常用流式输出，如果反向代理缓冲、超时或 HTTP 版本配置不对，用户会看到“等很久后一口气返回”或者中途断流。验收必须用真实浏览器测试流式输出，而不是只用短文本 curl。

六、证书坑：能HTTPS访问一次，不代表证书体系可靠

私有化 AI 项目经常卡在证书。内部系统需要 HTTPS，浏览器要信任，API 客户端要校验，WebSocket 和 SSE 要稳定，移动端或桌面端还可能有证书固定策略。证书不是上线时手工拷一份就完事，而是包含签发、安装、续期、信任链、私钥保护、域名匹配和监控。

Caddy 文档强调 automatic HTTPS 会自动申请和续期证书，并自动做 HTTP 到 HTTPS 重定向；Let's Encrypt 文档解释了 HTTP-01 和 DNS-01 challenge。公开域名、端口 80/443 可达时，HTTP-01 通常简单；内网服务、通配符证书、源站不暴露公网、严格防火墙场景下，DNS-01 更合适。私有化项目要按网络现实选择验证方式，而不是默认某一种。

第一类坑是内网域名拿公网证书。内部 .local、.internal、纯 IP、不可公网解析域名通常不适合公开 CA 证书。可以使用企业内部 CA、自签 CA 下发信任，或者使用可公开验证的真实域名配合内网解析。Caddy 对本地和内部主机会使用本地受信策略，但企业多终端环境需要明确客户端如何信任。

第二类坑是证书续期无人管。很多项目上线时证书有效，三个月后过期，全站不可用。Let's Encrypt 有 rate limits，失败重试太多还可能触发限制。续期要自动化，并监控证书剩余有效期、续期失败、DNS API token 状态和私钥文件权限。Kubernetes 环境可以用 cert-manager，单机环境可以用 Caddy、Certbot 或其他 ACME 客户端，但无论用什么，都要有告警。

第三类坑是反向代理和应用证书分层混乱。TLS 可以终止在网关，也可以端到端到后端服务。终止在网关时，后端要正确识别 X-Forwarded-Proto，否则会生成错误回调地址或混合内容；端到端时，内部服务也要信任证书链。不要让前端 HTTPS、后端 HTTP、回调 URL、Cookie secure 属性各自为政。

第四类坑是私钥到处复制。证书私钥属于敏感材料，不应散落在多个部署目录、聊天记录或工单附件里。应使用权限受控的 Secret、证书存储或自动化工具管理。备份证书时也要注意私钥加密和访问控制。

第五类坑是只测试浏览器首页。AI 应用还包括 API 调用、文件上传、流式输出、WebSocket、OAuth 回调、嵌入页面、管理后台和模型网关。证书验收要覆盖所有入口。尤其是浏览器里某些资源如果仍走 HTTP，会被拦截为混合内容。

七、日志坑：没有日志会瞎，有太多日志会死

日志是私有化项目排障的生命线，但日志设计不好也会造成事故。Kubernetes 官方日志架构文档指出，容器写 stdout/stderr 是最常见方式，但容器运行时原生能力不足以构成完整日志方案，集群级日志需要独立存储和生命周期。Docker 文档也提醒默认 json-file 日志驱动没有日志轮转，推荐在适当场景使用带轮转的 local 驱动。私有化项目如果不管日志，很容易磁盘被打满。

第一类坑是日志不结构化。AI 系统排障需要关联用户请求、模型请求、检索请求、工具调用、网关访问和错误栈。如果日志只是自然语言散文，很难查询。应至少包含时间、请求 ID、用户或租户标识、服务名、模型名、耗时、状态码、错误类型和关键阶段。OpenTelemetry 的日志数据模型提供了统一字段和 trace context 思路，适合把日志、指标、追踪关联起来。

第二类坑是敏感信息进日志。AI 应用处理用户输入、文件内容、检索片段、模型输出、API key、Cookie、令牌和内部路径。为了排障把完整 prompt 和响应都写进日志，很可能违反隐私和合规要求。生产日志要分级：默认记录元数据和错误摘要，必要时在受控开关下采样内容，并做脱敏和保留期控制。

第三类坑是日志没有集中收集。单机项目至少要配置日志轮转和目录监控；多容器项目要能按服务查看；Kubernetes 项目要有 DaemonSet 或平台日志采集，把 Pod 日志送到独立后端。否则 Pod 重建、节点宕机、容器删除后，关键证据就消失了。

第四类坑是只收应用日志，不收模型和 GPU 指标。用户说“系统慢”，原因可能是检索慢、模型排队、显存不足、网关超时、数据库慢查询、向量库索引异常或磁盘满。日志必须和指标一起看。vLLM、TGI、Triton 的 /metrics，Docker 或 Kubernetes 的资源指标，GPU 的 DCGM 指标，都应该纳入同一排障视图。

第五类坑是没有请求链路 ID。一次问答可能经过前端、后端、权限服务、知识库、向量库、重排模型、LLM 网关、模型服务和审计模块。没有统一 request id，就只能靠时间猜。生产系统应从入口生成 ID，向下游透传，并在日志、指标和错误响应中保留。用户报错时，客服或运维能用这个 ID 直接查链路。

八、备份坑：备份成功不等于能恢复

私有化 AI 项目里的数据不只是数据库。还包括用户账号、组织权限、知识库原文、向量索引、模型文件、配置文件、证书、审计日志、任务记录、上传文件、插件数据和部署脚本。很多团队只备份 PostgreSQL，结果恢复时发现对象存储、向量库和证书都缺，系统仍然不可用。

PostgreSQL 官方文档把备份分成 SQL dump、文件系统级备份和连续归档三类，并强调有价值数据应定期备份。对于小型系统，定期 pg_dump 可能够用；对于重要生产系统，只靠 dump 难以做到精确时间点恢复。PITR 需要基础备份和连续 WAL 归档，还要测试恢复流程。不能把数据库备份理解成“每天导出一个文件”这么简单。

第一类坑是没有恢复演练。备份日志显示成功，不代表备份可用。文件可能损坏，权限可能不对，WAL 不连续，恢复文档缺步骤，密钥丢失，对象存储缺文件。每个私有化项目都应该定期做恢复演练：新建一套环境，从备份恢复数据库、文件、知识库和配置，再跑业务验收。没有演练的备份只是心理安慰。

第二类坑是只备数据，不备配置。数据库恢复了，但应用环境变量、模型服务参数、证书、Caddyfile、Compose 文件、Helm values、权限策略、系统服务配置都没有，系统仍然起不来。备份清单必须覆盖“能让系统完整重建”的材料。部署代码和配置最好进入版本管理，敏感配置用受控 Secret 备份。

第三类坑是向量库和原文关系不清。知识库检索依赖原文、分块、嵌入模型、索引和元数据。向量索引可以备份，也可以从原文重建，但必须知道源文件、分块策略和嵌入模型版本。如果只备向量库，不备原文，无法验证和重建；如果只备原文，不记录索引策略，恢复后检索质量可能变化。

第四类坑是对象存储没有版本和防删。用户上传文件、知识库资料、模型文件和备份包常放在 S3 兼容对象存储或本地目录。MinIO Object Lock 文档说明对象锁可提供 WORM 不可变保护，版本控制也能减少误删风险。生产系统至少要考虑版本、保留期、跨盘或跨机复制，以及删除保护。

第五类坑是备份和加密密钥分离不当。备份加密是好事，但密钥如果只在原机器上，机器丢了备份也无法恢复；密钥如果明文放在备份旁边，加密又失去意义。要有独立、受控、可审计的密钥保管方式。

第六类坑是备份占满磁盘。模型文件和向量索引很大，日志和 WAL 也会增长。备份策略要有保留周期、空间监控和清理规则。restic 这类工具用 snapshot 和去重管理文件备份，但无论用什么工具，都要监控仓库健康和可恢复性。

九、升级坑：没有回滚的升级就是赌运气

私有化 AI 项目升级涉及应用代码、模型权重、推理框架、CUDA 镜像、驱动、容器 runtime、数据库 schema、向量索引、网关配置、前端资源和 Kubernetes 集群。任何一个环节变化，都可能影响用户体验。没有回滚方案的升级，本质是现场赌博。

第一类坑是跨版本跳跃太大。Kubernetes 官方升级文档明确说明 kubeadm 集群不支持跳过 minor 版本升级，version skew policy 也定义了组件之间支持的版本偏移。AI 项目同样如此：模型服务、框架和驱动之间有兼容窗口。不要从很旧版本直接跳到最新版本，除非官方明确支持并且测试覆盖充分。

第二类坑是数据库 schema 和代码版本不匹配。应用升级后需要迁移表结构，回滚代码时老版本可能读不了新结构。迁移前要备份，迁移脚本要幂等或可检测，回滚策略要明确。有些迁移只能前进不能后退，这种升级要安排维护窗口和数据快照。

第三类坑是模型升级没有业务对比。新模型可能更强，但输出风格、工具调用、上下文长度、显存占用、速度和幻觉率都可能变化。私有化客户关心稳定，不只关心榜单。升级模型前应准备固定评测集：常见问答、知识库引用、长文生成、权限拒答、工具调用、极端输入。通过后再灰度。

第四类坑是 Compose 更新误解。Docker Compose 官方文档说明 docker compose up 会在配置或镜像变化后停止并重建容器，并保留挂载卷；docker compose pull 只拉取镜像，不启动容器。现场常见错误是拉了新镜像但没有重建服务，或者重建时忘了持久卷。升级命令要写成明确流程，并在执行后检查镜像 ID、容器创建时间和服务健康。

第五类坑是 Helm 升级没有记录 values。Kubernetes 项目常用 Helm，但如果 values 文件散落在个人电脑或没有版本管理，后续升级无法复现。Helm 支持 upgrade 和 rollback，但 rollback 不是万能，尤其当 CRD、数据库和外部状态已经变化时。每次升级前要保存 chart 版本、values、镜像版本、数据库迁移状态和回滚条件。

第六类坑是驱动升级和业务升级绑在一起。GPU 驱动升级可能导致所有模型服务受影响。应尽量把基础设施升级和应用升级拆开，先在测试节点验证，再逐台滚动。Kubernetes 节点升级还要 drain，避免直接杀掉正在服务的推理任务。

十、验收坑：只看首页和健康检查不够

私有化 AI 项目验收不能只看服务是否启动。一个健康检查返回 ok，只说明进程活着，不说明用户能完成任务。真正验收应该覆盖端到端用户路径：登录、权限、知识库上传、索引完成、提问、引用、流式输出、长任务、并发、错误提示、管理后台、日志审计、备份恢复和升级回滚。

GPU 验收要看容器内 GPU 可见、模型加载到 GPU、并发请求下显存稳定、OOM 时有明确错误、服务恢复后不丢状态。网络验收要看内外域名、容器内 DNS、跨服务调用、反向代理、WebSocket 或 SSE、超时和大文件上传。证书验收要看浏览器信任、API 客户端信任、续期任务、证书剩余时间和混合内容。日志验收要看请求 ID、错误定位、磁盘轮转和敏感信息脱敏。备份验收要看恢复后的业务可用。升级验收要看版本记录和回滚演练。

验收还要模拟失败。断网、模型服务重启、向量库不可用、证书过期预警、磁盘接近满、GPU OOM、数据库连接满、对象存储不可用，这些都应该至少有降级表现和运维提示。生产级系统不是永不失败，而是失败时能被发现、能被定位、能被恢复。

对 AI 功能本身，也要做真实任务验收。知识库问答必须引用正确资料；私有数据不能越权；工具调用要真正执行；长文生成要满足字数和参考资料要求；Agent 任务要有完成证据。不能把“模型回答看起来不错”当作上线标准。

十一、运维坑：没有日常动作，系统会慢慢坏

私有化 AI 项目交付后，系统不会静止。模型文件增长，日志增长，知识库更新，证书快过期，用户增加，GPU 利用率变化，数据库膨胀，依赖出现安全更新。没有日常运维动作，系统会慢慢从可用变成不可维护。

日常巡检至少包括服务健康、GPU 状态、磁盘空间、证书有效期、数据库连接、备份结果、日志采集、请求错误率、模型延迟和队列长度。周级巡检可以看知识库索引失败、慢查询、对象存储容量、备份恢复抽查、异常用户行为和安全补丁。月级巡检可以评估模型版本、依赖升级、容量规划和灾备演练。

运维文档要面向现场人员。不要只写架构图，还要写常见故障处理：容器看不到 GPU 怎么查，证书续期失败怎么查，磁盘满先清哪里，模型 OOM 怎么降参数，知识库索引卡住怎么看，升级失败怎么回滚，备份怎么恢复到新机器。文档应随着真实事故更新。

权限和审计也属于运维。谁能上传知识库，谁能看日志，谁能导出对话，谁能更新模型，谁能重启服务，谁能访问备份，必须分清。私有化不是“放在内网就安全”，内网误操作和越权访问同样会造成事故。

容量规划也要进入运维节奏。AI 系统的增长不是线性的：一次知识库批量导入会让向量索引膨胀，一次模型替换会让显存需求跳变，一次用户推广会让并发峰值突然升高。运维人员要记录日常基线：每天请求量、平均上下文长度、知识库新增量、模型文件占用、日志增长速度、备份仓库增长速度和 GPU 峰值利用率。有基线，才知道什么时候该扩盘、加卡、拆服务或限制长任务；没有基线，容量问题通常会以磁盘满、OOM、超时和备份失败的形式突然出现。

十二、一份可执行的上线前清单

GPU 部分，确认宿主机驱动、CUDA 兼容关系、容器 runtime、容器内 nvidia-smi、模型显存占用、并发压测、GPU 指标和 OOM 恢复。Kubernetes 场景还要确认 device plugin 或 GPU Operator、节点 allocatable、测试 Pod、MIG 或共享策略、节点升级流程。

网络部分，确认内部服务名、外部域名、DNS 解析路径、反向代理、端口暴露、离线镜像、模型离线包、代理配置、SSE 或 WebSocket、超时和大文件上传。不要使用临时 IP 作为生产配置。

证书部分，确认域名策略、签发方式、信任链、自动续期、续期告警、私钥权限、回调地址、HTTPS 到后端协议、移动端或客户端信任。内网和公网混合时，特别检查 DNS-01 或内部 CA 方案。

日志部分，确认结构化字段、请求 ID、日志轮转、集中采集、脱敏策略、保留期、错误查询、模型指标、GPU 指标和磁盘告警。不要把完整敏感 prompt 默认写入永久日志。

备份部分，确认数据库、对象存储、知识库原文、向量索引或重建策略、配置、证书、部署文件、密钥保管、备份保留、异地或离线副本、恢复演练。验收必须包含一次从备份恢复的业务验证。

升级部分，确认版本记录、镜像固定、模型固定、迁移脚本、灰度方案、回滚条件、Helm values 或 Compose 文件版本管理、驱动和框架兼容、升级后指标对比。没有回滚路径的升级不要进入生产窗口。

十三、现场排障顺序：先分层，再动手

私有化 AI 现场排障最怕一上来就改配置。GPU 不通就换镜像，证书失败就换代理，问答慢就换模型，日志太大就删目录，这些动作可能暂时让服务恢复，却会把根因盖住。更稳妥的方法是按层排查，每一步都留下证据：现象是什么，影响范围是什么，最近变更是什么，哪个层级已经确认正常，哪个层级仍有疑点。

GPU 问题先从宿主机开始。第一步看硬件是否存在、驱动是否加载、nvidia-smi 是否正常。第二步看容器 runtime，运行最小 CUDA 容器验证容器内能否看到 GPU。第三步看模型服务镜像，确认 CUDA 库、框架版本和启动参数。第四步看应用指标，确认推理请求真的进入 GPU，而不是服务启动后仍走 CPU。Kubernetes 环境再加两步：节点是否暴露 nvidia.com/gpu，测试 Pod 是否能申请并使用 GPU。这个顺序可以避免把节点问题误判成应用问题。

网络问题先看访问方向。用户浏览器访问失败，要从浏览器 DNS、TLS、反向代理、后端路由、上游服务逐层查；服务间调用失败，要从容器或 Pod 内部解析和连通性查；证书签发失败，要从 CA 验证方视角查域名和端口；模型下载失败，要从出网代理、镜像仓库和离线包查。不要只在宿主机上 curl 成功就认为网络正常，因为容器、Pod、浏览器和证书机构看到的网络不是同一个视角。

证书问题先分清是签发失败、安装失败、信任失败还是续期失败。签发失败通常看 DNS、端口、challenge 类型和 rate limit；安装失败看文件路径、权限和代理加载；信任失败看客户端信任链、中间证书和域名匹配；续期失败看定时任务、DNS API token、ACME 客户端日志和防火墙。把这几类混在一起，会导致反复重签却解决不了浏览器不信任，或者反复导入证书却解决不了续期。

性能问题不能只看模型。用户觉得慢，可能是登录慢、知识库检索慢、重排慢、模型 prefill 慢、decode 慢、流式被代理缓冲、前端渲染慢，也可能是日志写盘和数据库慢查询拖住后端。排查时要用同一个请求 ID 串起入口、检索、模型和响应输出，结合指标看每段耗时。没有链路 ID 时，至少要在同一时间窗口对齐网关日志、应用日志和模型指标，避免凭感觉调参数。

数据问题先判断能否恢复。误删知识库、数据库迁移失败、对象存储丢文件、向量索引损坏，都不要急着在原环境继续操作。先冻结现场，确认最近可用备份、备份完整性、恢复目标环境和业务影响范围。能在新环境恢复验证，就不要直接在生产库上试错。私有化项目最容易把一次小故障扩大成大事故，原因就是没有先保护现场。

升级问题先回看变更清单。今天变了什么：镜像、模型、配置、证书、网关、驱动、节点、数据库、索引、前端静态文件，还是外部 DNS？如果没有变更记录，只能靠猜。每次升级都应留下版本表和执行日志，出问题时才能快速判断是应用回滚、模型回滚、配置回滚，还是必须做数据恢复。可回滚不是一句承诺，而是排障时能用的真实路径。

十四、交付物边界：交付系统，不是交付一堆命令

很多私有化 AI 项目最后交付给客户的，是一个压缩包、一组镜像、几条部署命令和一个管理员账号。这种交付能跑起来，但很难长期运维。生产级交付物应该覆盖运行、观测、恢复和升级，而不是只覆盖安装。客户真正需要的不是“某工程师在现场能装好”，而是“换一个值班人员也能按文档判断系统是否健康，并在常见故障中恢复服务”。

最少应交付一份环境清单。清单里写明操作系统、内核、GPU 型号、驱动版本、CUDA 或 ROCm 版本、Docker 或 containerd 版本、Kubernetes 版本、镜像版本、模型版本、端口、域名、证书方式、数据目录、备份目录和日志目录。这份清单看似普通，但在故障和升级时价值很高。没有清单，现场人员连“现在是什么版本”都要现查。

第二份交付物是部署清单。Compose 项目要有 compose.yaml、环境变量模板、持久卷说明、启动顺序、更新命令和回滚命令。Kubernetes 项目要有 Helm chart 或 manifests、values 文件、Secret 管理方式、命名空间、Ingress、PVC、资源限制、节点选择和升级步骤。所有文件都应该有版本管理，不应只存在某台工程师电脑里。

第三份交付物是验收报告。报告不应只写“部署成功”，而要列出已验证的用户路径和运维路径：登录、问答、知识库上传、引用返回、流式输出、并发压测、GPU 使用、日志查询、证书状态、备份恢复、升级回滚。每项验收最好有时间、版本和结果。这样后续出现争议时，可以清楚知道上线时到底验证过什么。

第四份交付物是运维手册。手册要写日常巡检、常见故障、日志位置、指标入口、备份位置、恢复步骤、证书续期、模型更新、用户管理和权限变更。不要把手册写成产品介绍，也不要只写架构原理。现场人员要的是可执行动作：看到什么现象，先查哪里，正常值是什么，异常时怎么处理，什么时候升级给研发。

第五份交付物是恢复包或恢复方案。恢复方案至少说明如何在一台新机器上重建系统：安装基础环境，恢复配置，恢复数据库，恢复对象文件，恢复知识库或重建索引，导入证书或重新签发证书，启动服务，做业务验收。真正做过恢复演练后，恢复方案才可信。没有演练的恢复文档通常会漏掉密钥、权限、路径和初始化顺序。

第六份交付物是升级策略。它要说明哪些组件可以独立升级，哪些组件必须一起升级，升级前要备份什么，升级后要验证什么，失败时如何回滚，哪些变更需要维护窗口。AI 项目尤其要把模型升级单独列出来，因为模型升级可能改变输出质量、显存需求和延迟曲线。不要把模型权重当作普通静态文件随手替换。

交付物还要避免泄露敏感信息。文档中可以写变量名和路径，不应写明文密钥；可以写证书管理方式，不应把私钥粘进去；可以写管理员创建流程，不应把永久密码写进 Word 文档。私有化交付常常要经过邮件、工单、共享盘流转，敏感材料必须有单独通道和权限控制。

最终，交付边界要让客户和实施团队都清楚：哪些属于应用厂商负责，哪些属于客户基础设施负责，哪些属于双方协作。GPU 驱动谁维护，域名谁解析，证书 DNS token 谁保管，备份介质谁提供，安全补丁谁升级，日志保留策略谁审批，这些都要在上线前说清。边界不清时，小问题会变成扯皮，大问题会变成事故。

十五、结语：私有化AI拼的是系统能力

私有化 AI 项目真正的门槛，是把模型能力变成可运行、可观测、可恢复、可升级、可审计的系统能力。GPU 决定算力能不能稳定释放，网络决定服务能不能被正确访问，证书决定信任链能不能长期成立，日志决定问题能不能定位，备份决定事故后能不能回到可用状态，升级决定系统能不能持续演进。任何一项薄弱，都会把看起来很先进的 AI 应用拖回手工作坊。

生产级交付不需要把所有平台一次做得很重，但必须把关键链路做实。能用 GPU，就证明容器内真实推理使用 GPU；说有证书，就证明续期和告警存在；说有日志，就证明能按请求 ID 查到完整链路；说有备份，就证明从备份恢复过；说能升级，就证明有版本记录和回滚方案。这些检查要落到日常流程里。私有化 AI 的可信度，不在宣传页里，而在这些可验证的细节里。

参考资料

]]>https://localaihub.com/topic/19/私有化ai项目踩坑清单-gpu-网络-证书-日志-备份和升级RSS for NodeWed, 03 Jun 2026 18:50:27 GMTThu, 21 May 2026 21:28:02 GMT60