typesense在linux上docker部署失败主因是关键参数缺失：必须显式指定--api-port=8108、--host=0.0.0.0、--enable-cors，且-p 8108:8108端口映射与api-key纯字母数字组合缺一不可。
Typesense 在 Linux 上安装不难，但直接 docker run 启动后连不上、搜不到数据、外网访问失败——这些问题几乎都出在几个关键配置点上，而不是“没装好”。下面直说怎么做、为什么这么设、哪些地方一错就卡死。
docker run 启动 Typesense 时必须加的参数
很多人复制网上命令启动后，curl http://localhost:8108/health 返回 connection refused，其实是容器根本没真正监听 8108。核心原因：缺少 --api-port 显式声明，或端口映射不匹配。
-
-p 8108:8108必须存在，且主机端口（左边）不能被占用；Ubuntu 上常被 snap 的lxd或其他服务占掉，用sudo ss -tulpn | grep :8108检查 -
--api-port=8108要显式写进命令里，否则 Typesense 可能默认用 8107（peering 端口），导致 API 不通 -
--enable-cors不是可选——前端调用时若没它，浏览器会报Blocked by CORS policy -
--api-key值不能含特殊字符（如/、=、空格），否则 Docker 启动失败但不报错，只静默退出；建议用 16 位以上纯字母数字组合，例如AbcXyz9mNpQr2StUv
正确启动命令示例：
docker run -d \ --name typesense \ -p 8108:8108 \ -v ~/typesense-data:/data \ typesense/typesense:29.0 \ --data-dir /data \ --api-key=AbcXyz9mNpQr2StUv \ --api-port=8108 \ --enable-cors
Typesense 客户端连接失败的常见原因
Python 或 JS 客户端初始化后调 .collections.create() 报 ConnectionError 或 Timeout，大概率不是代码问题，而是网络或认证链路断了。
- 客户端 host 写
localhost：仅在本机运行脚本时有效；如果 Python 脚本跑在另一台机器，host 必须填服务器真实 IP，不能是127.0.0.1或localhost - API key 错位：客户端传的是
api_key字段，但 Typesense 启动时用的是--api-key参数，两者值必须完全一致（大小写敏感） - 防火墙拦截：Ubuntu 默认启用
ufw，需手动放行sudo ufw allow 8108；CentOS 则检查firewalld是否开了publiczone 并允许端口 - 未等容器就绪就发请求：Docker 启动容器很快，但 Typesense 初始化索引目录要几秒，建议首次连接前加
sleep 3或轮询/health接口直到返回{"ok":true}
数据持久化和重启后丢失的坑
很多人发现重启服务器或 docker restart typesense 后，之前建的 collection 全没了——这是因为没正确挂载或权限不对。
-
-v ~/typesense-data:/data中的~/typesense-data目录必须提前创建，且 Docker 进程有写权限；用ls -ld ~/typesense-data确认属主是root或docker组用户 - 不要用
/tmp下的路径做 data dir：某些系统重启后清空/tmp，导致数据消失 - 确认容器内进程实际用了挂载路径：进入容器执行
docker exec -it typesense sh -c 'ls -l /data'，应看到typesense.db和typesense.lock文件 - 升级镜像时别删容器：用
docker stop typesense && docker rm typesense再run，会导致挂载卷被忽略；应直接docker pull typesense/typesense:29.0 && docker restart typesense
外网访问必须绕过的两个关卡
本地能连，但手机或公司电脑访问 http://你的公网IP:8108/health 超时？这和 Typesense 本身无关，是网络层限制。
- 家用宽带没有固定公网 IP：绝大多数家庭宽带分配的是内网 IP（如
10.x.x.x），路由器 WAN 口显示的也不是真实公网 IP；此时必须用内网穿透工具（如你知识库提到的路由侠），不能直接端口映射 - 云服务器安全组没开 8108：阿里云、腾讯云默认只放行 22/80/443，必须手动在控制台添加入方向规则，协议选 TCP，端口填
8108 - Typesense 不监听 0.0.0.0：启动命令中没加
--host 0.0.0.0，它默认只绑定127.0.0.1；补上这个参数才能响应外部请求 - 反向代理误配：如果套了 Nginx，注意它默认不转发非标准端口的 Upgrade 头，搜索请求可能卡在 OPTIONS 预检；要么关 CORS（不推荐），要么在 Nginx 配置里加
add_header 'Access-Control-Allow-Origin' '*';和相关头字段
最易被忽略的一点：Typesense 的 --host 参数默认值是 127.0.0.1，即使你映射了端口、开了防火墙、配了安全组，只要没显式写 --host 0.0.0.0，它就拒绝一切来自 localhost 外的连接——这个行为不会报错，只会静默丢包。
