N.E.K.O.Docker部署完整指南Compose一键启动、SSL证书配置与旧版本迁移避坑全解【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.ON.E.K.O 是一只住在实时环境里的 AI 猫娘——会主动找你聊天、共享你的媒体内容还能真正帮你把事办完由具身情感引擎驱动。对于想把它跑在自己服务器上的新手来说Docker 是最省心的部署方式用 Docker Compose 一键启动Nginx 反向代理、SSL 证书自动生成、数据持久化全部开箱即用。本文带你在 10 分钟内完成 N.E.K.O Docker 部署并讲透 SSL 证书配置与旧版本迁移这两个最容易踩的坑。 部署前准备选择正确的镜像版本N.E.K.O 的 Docker 镜像分为两种形态先选对再启动版本大小特点适合谁standard标准版约 1.5 GB首次启动时下载 Chromium磁盘有限、能接受首启稍慢full完整版约 2.5 GB构建时已内置 Chromium想开箱即用、不想等下载镜像 tag 的选择同样关键详见 docker/README_Docker.md✅生产环境用latest默认值只在正式发布时更新稳定可预期✅ 需要锁定版本时用0.8.0-standard这类具体 release tag⚠️不要在生产使用ci-standard/ci-full这是滚动 tag每次主线提交都会覆盖仅用于内测 中国大陆用户默认 Compose 文件已内置镜像代理源如网络不佳可在 docker/docker-compose.yml 顶部按注释切换备用源或通过NEKO_IMAGE变量覆盖镜像地址。 Docker Compose 一键启动完整步骤所有部署文件都在仓库的docker/目录中官方教程为 docker/README_Docker.md第 1 步获取仓库git clone https://gitcode.com/gh_mirrors/ne/N.E.K.O cd N.E.K.O/docker第 2 步创建并填写环境变量cp env.template .env nano .env # 至少填入 NEKO_CORE_API_KEY第 3 步一键启动docker compose up -d docker compose logs -f # 查看启动日志启动成功后打开http://服务器IP:48911即可访问 Web 界面。端口说明容器只对外暴露两个端口——HTTP48911Nginx 80和 HTTPS48912Nginx 443。记忆服务、Agent 服务、插件服务全部走容器内 Nginx 反向代理无需单独放通端口防火墙策略可以非常简单。⚙️ 配置核心参数环境变量到底什么时机生效这是新手最容易误解的一点来自 docker/README_Docker.md 的原文语义环境变量只在首次启动时生成持久化初始配置core_config.json。之后一切以容器内/home/neko/.local/share/N.E.K.O/config/的运行时配置为准——重启不会用环境变量重新覆盖它。也就是说改了.env再docker compose up -d配置可能毫无变化。正确姿势是日常修改走Web UI 设置页或手动编辑持久化目录里的core_config.json确实想用环境变量强制重新生成时显式设置NEKO_FORCE_ENV_UPDATE⚠️ 它会覆盖现有配置动手前先备份。关键环境变量速查表变量说明默认值NEKO_CORE_API_KEY核心 API Key必填无NEKO_CORE_API核心 API 提供商qwenNEKO_ASSIST_API辅助 API 提供商记忆、情感分析等qwenNEKO_MAIN_SERVER_PORT主服务器端口48911TZ容器时区IANA 名称Asia/ShanghaiNEKO_IMAGE_VERSION镜像 tag 后缀latestAPI 提供商支持qwen阿里云推荐有免费额度、openai、glm智谱、step阶跃星辰、free免费版等辅助 API 还多了silicon、grok、doubao。完整的 60 配置项参考 docker/CONFIG_REFERENCE.md模板注释见 docker/env.template。 SSL 证书配置自动生成与热重载N.E.K.O 的 docker/entrypoint.sh 内置了一套相当完整的 SSL 管理机制启动日志里那份五星神级证书报告就是它干的机制行为自动生成首次启动在/home/neko/ssl/生成自签名证书RSA 4096 位默认有效期 1000 年文件为N.E.K.O.crt/N.E.K.O.key启动校验每次启动验证 PEM 格式、私钥类型RSA/EC、证书与私钥是否匹配校验失败且AUTO_REGENERATE_CERT1时自动重新生成热重载Nginx 每 5 分钟检查一次配置和证书文件变化替换证书后无需重启容器即生效SSL 相关环境变量变量说明默认值SSL_DOMAIN证书绑定域名建议改成自己的域名project-neko.onlineSSL_DAYS自签证书有效期天365000DISABLE_SSL设为1时 Nginx 仅监听 80 端口未设置启用AUTO_REGENERATE_CERT校验失败时是否自动重新生成1NEKO_TRUSTED_HOSTS经 Nginx 代理时的应用层可信主机取SSL_DOMAIN⚠️生产部署提醒容器自动生成的是自签名证书浏览器会提示不受信任。真实公网部署应把自己的托管证书或 CA 签发证书覆盖到持久化的neko-home/ssl/下文件名保持N.E.K.O.crt/N.E.K.O.key或在可信的反向代理上做 TLS 终结。 旧版本迁移避坑为什么升级后数据全没了这是升级时最经典的一个坑官方文档 docs/deployment/docker.md 用红色警告框专门标注了。坑的根源旧版 Compose 使用./N.E.K.O./ssl两个独立挂载新版合并为一个./neko-home挂载到/home/neko。如果升级时不迁移数据容器会对着一个空目录启动——它启动一切正常、API Key 也会从环境变量重新生成看起来没有任何异常但角色、记忆和插件全部不见了。数据没有被删除只是不再被挂载了。迁移三步法先导出再停容器顺序至关重要docker compose down会删除容器而容器可写层里的数据可能在任何地方都不再有第二份。第 1 步从容器内导出数据必须在删除容器之前mkdir -p neko-home/.local/share/N.E.K.O neko-home/ssl # 检查容器实际挂载点判断是否已是新布局 docker inspect neko --format {{range .Mounts}}{{println .Destination}}{{end}} # 导出旧版遗留的引导配置若存在 docker cp neko:/app/config/core_config.json \ ./neko-home/.local/share/N.E.K.O/config/core_config.json # 导出应用数据目录尾部 /. 复制内容避免嵌套一层 docker cp neko:/home/neko/.local/share/N.E.K.O/. \ ./neko-home/.local/share/N.E.K.O/第 2 步停止容器并合并宿主目录docker compose down # 若第 1 步已从容器导出数据则不要合并宿主旧的 N.E.K.O/ 目录 # 旧版快速开始挂载路径与服务实际写入路径不一致里面的文件可能是假数据 [ -d N.E.K.O ] cp -a N.E.K.O/. neko-home/.local/share/N.E.K.O/ [ -d ssl ] cp -a ssl/. neko-home/ssl/ # 容器内应用用户固定为 uid/gid 1000宿主 uid 不同时需修正属主 [ $(id -u) 1000 ] || sudo chown -R $(id -u):$(id -g) neko-home第 3 步重新启动并验收docker compose up -d curl -f http://127.0.0.1:48911/health迁移避坑清单✅先导出、后 down数据导出失败磁盘满、权限不足、daemon 不可达就先修好再走下一步✅ 同名文件冲突时以旧数据为准✅ 升级前把neko-home和logs两个目录完整备份一遍✅ 若只是改 API Key 这类配置直接编辑持久化配置或用 Web UI 即可无需触发迁移✅ 升级后检查 Web UI 里角色列表和记忆是否正常加载。 故障排查5 个高频问题一次解决症状原因与排查改了.env但配置不生效环境变量仅首次生成初始配置改用 Web UI 修改或备份后设置NEKO_FORCE_ENV_UPDATEHTTPS 报证书错误自签名证书属预期现象用docker exec neko bash进入容器执行openssl x509 -in /home/neko/ssl/N.E.K.O.crt -noout验证或按上文替换托管证书Web UI 打不开确认48911端口已放通docker compose ps看容器状态docker logs neko看启动日志访问/health应返回healthy标准版首启卡在启动中首次需下载 Chromium耐心等待或改用latest-full完整版镜像备份/编辑neko-home提示权限拒绝容器内用户为 uid/gid 1000宿主 uid 不一致时用sudo或修正属主进容器检查生效配置的快速命令docker exec neko cat /home/neko/.local/share/N.E.K.O/config/core_config.json docker exec neko env | grep NEKO_✅ 小结选对镜像生产用latest或钉死 release tag怕首启等待就选latest-full一键启动cp env.template .env→ 填 API Key →docker compose up -d两个端口48911/48912放通即可理解配置时机环境变量只初始化一次之后走 Web UI 或持久化配置SSL 免维护自签证书自动生成、校验、热重载全内置公网部署替换成托管证书即可升级先备份旧版两挂载布局升级必须先导出、后 down这是数据安全的生命线。 参考文件部署教程docker/README_Docker.md英文版部署与迁移全文docs/deployment/docker.mdCompose 配置docker/docker-compose.yml环境变量模板docker/env.template完整配置参考docker/CONFIG_REFERENCE.md启动脚本Nginx/SSL/迁移逻辑docker/entrypoint.sh镜像构建文件docker/Dockerfile、docker/Dockerfile.full【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.O创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考