Typesense 官方自 v25.0 起弃用 deb/rpm 包，不提供 apt/yum 安装支持，因其 Rust 编译产物对 glibc 和动态库敏感，为规避环境兼容问题，仅发布 Docker 镜像。
Typesense 在 Linux 上能直接跑，但必须用 Docker 启动；不支持裸机二进制直装（官方已明确弃用），硬要编译会卡在 Raft 依赖和 Rust 工具链上。
为什么不能用 apt/yum 直接装 typesense
Typesense 官方从 v25.0 起就不再提供 deb/rpm 包，apt install typesense 或 yum install typesense 会返回 Package not found。它本质是 Rust 编写的单体二进制，但官方只打包成 Docker 镜像发布，原因很实际：
- 避免用户环境缺失
libssl、libz等动态库导致运行时报symbol lookup error - Rust 编译产物对 glibc 版本敏感，Ubuntu 20.04 和 CentOS 7 的 libc 差异会让同一二进制崩溃
- Docker 镜像内含完整运行时，省去用户手动处理
ulimit -n、vm.max_map_count等内核参数
docker run 启动时最关键的四个参数
下面这行命令不是示例，是生产可用的最小可行配置（以 Ubuntu 22.04 为例）：
docker run -d \ --name typesense \ --restart unless-stopped \ -p 8108:8108 \ -v /opt/typesense-data:/data \ typesense/typesense:29.0 \ --data-dir /data \ --api-key=AbC123xYz987 \ --enable-cors
容易被忽略但致命的点：
Zynq Linux Hardware Debug
下载
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
-
-v /opt/typesense-data:/data：宿主机路径必须存在且 Docker 可写，mkdir -p /opt/typesense-data && chown 1001:1001 /opt/typesense-data（Typesense 容器默认以 UID 1001 运行） -
--api-key值不能含空格或特殊字符（如$、@），否则容器启动后立即退出，日志里只显示invalid argument - 如果服务器开了防火墙（如
ufw或firewalld），必须放行8108端口：sudo ufw allow 8108 -
--enable-cors不是可选——前端 JS 直连 Typesense 必须加它，否则浏览器报Blocked by CORS policy
外网访问时，curl http://localhost:8108/health 成功但外网打不开？
这是最常卡住的环节。根本原因不是 Typesense 本身，而是网络层没透出：
- 云服务器（如雨云、腾讯云）控制台安全组必须手动放行
8108TCP 入口，仅开防火墙不够 - 家用宽带路由器需做端口映射（Port Forwarding），目标 IP 填你 Linux 机器的局域网 IP（如
192.168.1.100），外部端口建议和内部一致（8108） - 如果你用的是 NAT 模式虚拟机（比如 VMware/VirtualBox），宿主机 Windows/Mac 必须额外开启端口转发，否则
http://宿主机IP:8108也访问不到 - 别信“内网穿透工具自动搞定”——路由侠这类工具需要 Windows 客户端配合，Linux 服务器上只跑 Docker 容器是无效的
想用 HTTPS 或反向代理？Nginx 配置里必须加这两行
直接暴露 8108 端口不安全，推荐用 Nginx 做反代。关键配置不是常规的 proxy_pass，而是：
location / {
proxy_pass http://127.0.0.1:8108;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# 下面两行缺一不可
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
}漏掉 proxy_http_version 1.1 会导致批量导入数据时连接被重置；漏掉 Upgrade 头，WebSocket 类功能（如实时搜索建议）会失败。Typesense 内部大量使用 HTTP/1.1 流式响应，这点和 Elasticsearch 不同。
