一句话理解#

镜像是安装包，容器是正在运行或已停止的一次实例，数据卷是要跨容器保留的数据。

你的 TEI 部署可这样理解：

1
TEI 镜像
2
  ghcr.io/huggingface/text-embeddings-inference:89-1.9
3
                 |
4
                 v
5
TEI 容器（名字：tei）
6
  端口：127.0.0.1:8080 -> 容器 80
7
  GPU：nvidia.com/gpu=all
8
                 |
9
                 v
10
数据卷（名字：tei-data）
11
  保存 Hugging Face 下载的模型缓存

非常重要：本章固定使用 sudo podman#

Podman 的 rootful 和 rootless 是两套隔离环境：

1
sudo podman ps       -> root 管理的容器（本章使用）
2
podman ps            -> 当前用户管理的另一套容器

你先前用 sudo podman run ... --name tei 创建服务，所以之后查看、停止、启动都使用 sudo podman。不要因为终端里少打了 sudo，以为 tei 消失了。

检查点#

运行：

1
sudo podman ps -a

预期：列表中能看到名为 tei 的容器；STATUS 可以是 Up ...（运行中）或 Exited ...（已停止但仍存在）。

心智模型#

ps 看状态，logs 看过程，curl 问服务，nvidia-smi 看 GPU。

1. 看正在运行的容器#

1
sudo podman ps

如果有 tei，并且 STATUS 显示 Up，服务正在运行。

要连同停止的容器一起看：

1
sudo podman ps -a

2. 看 TEI 启动日志#

1
sudo podman logs -f tei

-f 表示持续跟随日志，和 tail -f 类似。首次启动下载模型时可能较久；看到服务开始监听后按 Ctrl+C 退出看日志，不会停止 TEI 容器。

只看最后 100 行：

1
sudo podman logs --tail 100 tei

3. 确认端口只对本机开放#

1
sudo ss -ltnp | grep ':8080'

预期包含 127.0.0.1:8080。这代表只有 Fedora 本机能访问 TEI；之后由 Cloudflare Tunnel 从本机转出 HTTPS，不需要把 8080 暴露到公网。

4. 请求 TEI 的健康信息#

先临时读入 API Key，避免把密钥直接写进 shell 历史：

1
read -rsp 'TEI API Key: ' TEI_API_KEY
2
echo

再请求：

1
curl http://127.0.0.1:8080/info \
2
  -H "Authorization: Bearer $TEI_API_KEY"

成功时会返回 JSON，通常能看到模型、最大输入长度或服务能力等信息。完成后清掉当前终端变量：

1
unset TEI_API_KEY

5. 确认容器看得见 GPU#

先看宿主机：

1
nvidia-smi -L

再看 NVIDIA CDI 是否暴露给 Podman：

1
nvidia-ctk cdi list

预期可看到 nvidia.com/gpu=all。如果没有，先确认 Toolkit 已安装，再运行：

1
sudo systemctl restart nvidia-cdi-refresh.service
2
nvidia-ctk cdi list

不确定容器是否真的拿到了 GPU 时，运行 NVIDIA 官方的最小验证：

1
sudo podman run --rm \
2
  --device nvidia.com/gpu=all \
3
  --security-opt=label=disable \
4
  ubuntu \
5
  nvidia-smi -L

输出应与宿主机的 nvidia-smi -L 一样能看到你的显卡。--rm 表示这个测试容器结束后自动删除。

常见坑#

• curl 返回 401：TEI 在运行，但 Authorization: Bearer ... 的 Key 不对或漏传了。
• Connection refused：容器没有运行，或端口映射不是 127.0.0.1:8080:80。
• nvidia-ctk cdi list 没有 GPU：先修 Toolkit / CDI，不要继续排 TEI 模型。
• podman ps 空列表而 sudo podman ps 有结果：你混用了 rootless 和 rootful 命令。

一句话理解#

stop 是关服务但保留容器；start 是按原配置再开同一个容器；restart 是先关再开。

关闭后想再次开启#

1
sudo podman start tei
2
sudo podman ps

这是你现在最常用的两行。它不会重新下载模型，因为 tei-data 卷仍然挂在同一个容器上。

主机关机后再开机#

在还没有配置自动启动前，主机启动后手动运行：

1
sudo podman start tei
2
sudo podman logs --tail 50 tei

然后重复上一关的 /info 检查。

容器故障后的最小排查顺序#

1
sudo podman ps -a
2
sudo podman logs --tail 100 tei
3
sudo podman inspect --format '{{.State.Status}}' tei

先看最后的日志错误，再决定是否需要重启。不要上来就删除容器。

心智模型#

容器是可重建的，模型缓存卷才是你不想重复下载的东西。

例如你修改了镜像版本、模型名、端口或 GPU 参数时，需要重建容器：

1
sudo podman stop tei
2
sudo podman rm tei

这两条命令只删除名为 tei 的容器；只要你重建时仍挂载：

1
tei-data:/data:Z

已经下载的模型缓存仍在。

不要执行这条命令#

1
sudo podman volume rm tei-data

它会删除模型缓存卷。只有当你确认要释放空间、接受下次重新下载模型时，才考虑它。

先确认卷存在：

1
sudo podman volume inspect tei-data

重建后的 GPU TEI 最小模板#

只有在 tei 已停止并删除后，才运行下面模板。先在当前终端输入 Key：

1
read -rsp 'TEI API Key: ' TEI_API_KEY
2
echo

再创建容器：

1
sudo podman run -d \
2
  --name tei \
3
  --pull=always \
4
  --device nvidia.com/gpu=all \
5
  --security-opt=label=disable \
6
  -p 127.0.0.1:8080:80 \
7
  -v tei-data:/data:Z \
8
  -e API_KEY="$TEI_API_KEY" \
9
  ghcr.io/huggingface/text-embeddings-inference:89-1.9 \
10
  --model-id Qwen/Qwen3-Embedding-0.6B \
11
  --served-model-name qwen3-embedding-0.6b
12

13
unset TEI_API_KEY

这条命令的核心映射：

为什么不用旧的 podman generate systemd#

Podman 当前官方推荐 Quadlet：你写一个 .container 声明文件，Podman / systemd 在启动时生成 tei.service。它比从旧容器一次性“生成 service 文件”更适合长期维护。

本节会把你当前手动创建的 tei 容器迁移为由 systemd 管理的同名 tei 服务，继续复用原来的 tei-data 卷。

迁移时会删除旧的 tei 容器，但不会删除 tei-data 数据卷。

1. 停止并移除手动容器#

1
sudo podman stop tei
2
sudo podman rm tei
3
sudo podman volume inspect tei-data

最后一条仍能输出卷的 JSON，才说明模型缓存被保留。

2. 单独保存 API Key#

创建仅 root 可读的目录：

1
sudo install -d -m 0700 /etc/tei
2
sudoedit /etc/tei/tei.env

在编辑器中写入一行，把值替换成你自己生成的随机 Key：

1
API_KEY=替换成你的真实TEI密钥

保存并退出后限制文件权限：

1
sudo chmod 600 /etc/tei/tei.env
2
sudo ls -l /etc/tei/tei.env

预期权限类似：

1
-rw-------. 1 root root ... /etc/tei/tei.env

3. 创建 Quadlet 声明#

创建目录和文件：

1
sudo install -d -m 0755 /etc/containers/systemd
2
sudoedit /etc/containers/systemd/tei.container

写入以下完整内容：

1
[Unit]
2
Description=TEI embedding server
3
Wants=network-online.target
4
After=network-online.target
5

6
[Container]
7
Image=ghcr.io/huggingface/text-embeddings-inference:89-1.9
8
ContainerName=tei
9
Pull=missing
10
AddDevice=nvidia.com/gpu=all
11
SecurityLabelDisable=true
12
PublishPort=127.0.0.1:8080:80
13
Volume=tei-data:/data:Z
14
EnvironmentFile=/etc/tei/tei.env
15
Exec=--model-id Qwen/Qwen3-Embedding-0.6B --served-model-name qwen3-embedding-0.6b
16

17
[Service]
18
Restart=always
19
TimeoutStartSec=900
20

21
[Install]
22
WantedBy=multi-user.target

这不是普通 Python 配置，也不是直接执行的 shell 脚本：它是 Quadlet 的声明。Podman 会把 [Container] 翻译成一次 podman run，systemd 负责启动、停止和主机重启后的恢复。

4. 让 systemd 读取并启动它#

1
sudo systemctl daemon-reload
2
sudo systemctl start tei.service
3
sudo systemctl status --no-pager tei.service

预期 Active: 是 active (running)。

注意：不要运行 sudo systemctl enable tei.service。 Quadlet 产生的 service 属于生成单元，官方文档说明不能这样 enable；.container 文件内的 [Install] / WantedBy=multi-user.target 会在生成阶段处理开机启动。

5. 用 systemd 管理自动启动后的服务#

以后修改 /etc/containers/systemd/tei.container 后，固定执行：

1
sudo systemctl daemon-reload
2
sudo systemctl restart tei.service

本关检查点#

1
sudo systemctl status --no-pager tei.service
2
sudo podman ps

两处都应能确认 tei 正在运行。然后再使用第二关的 curl /info 验证 HTTP 接口。

数据流#

1
Dify Cloud
2
  -> HTTPS https://embed.example.com
3
  -> Cloudflare Tunnel（Fedora 上的 cloudflared）
4
  -> http://127.0.0.1:8080
5
  -> TEI 容器
6
  -> GPU / Qwen3 Embedding 模型

这里的关键边界：TEI 仍然只监听 127.0.0.1；Cloudflare Tunnel 作为 Fedora 本机客户端向外建立连接。不要为了让 Dify 能访问就把 TEI 改成 0.0.0.0:8080。

接入前一次性验证：

1
sudo systemctl status --no-pager tei.service
2
sudo podman ps
3
sudo ss -ltnp | grep ':8080'

然后请求 /info：

1
read -rsp 'TEI API Key: ' TEI_API_KEY
2
echo
3
  curl http://127.0.0.1:8080/info \
4
    -H "Authorization: Bearer $TEI_API_KEY"
5
  unset TEI_API_KEY

全部成功后，Cloudflare Tunnel 的服务地址填写：

1
http://127.0.0.1:8080

而 Dify 的 TEI Provider 使用：

1
Server URL: https://你的子域名
2
API Key: 与 /etc/tei/tei.env 中 API_KEY 相同
3
Model name: qwen3-embedding-0.6b