项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 3264
使用教程
环境要求
- Linux 系统(Docker 部署指南面向 Linux)
- 已安装 Docker 与 Docker Compose
- 宿主机普通用户 uid/gid 为 1000(容器内应用用户固定为 1000)
- 端口 48911(HTTP)与 48912(HTTPS)未被占用
安装与启动步骤
-
1准备 Docker 环境
确认系统为 Linux,并已装好 Docker 与 Docker Compose;README 未提供安装 Docker 的命令,请自行准备。
-
2写 docker-compose.yml
在部署目录新建 docker-compose.yml,填入 README 给出的官方配置,注意 48911/48912 端口映射与两个数据卷。
version: '3.8' services: neko-main: image: docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest container_name: neko restart: unless-stopped ports: - "48911:80" - "48912:443" volumes: - ./neko-home:/home/neko - ./logs:/app/logs networks: - neko-network networks: neko-network: driver: bridge -
3启动容器
在 docker-compose.yml 同级目录执行,-d 为后台运行。首次启动会自动生成自签名 SSL 证书到 ./neko-home/ssl/。
docker-compose up -d -
4查看日志
跟踪启动日志,确认容器正常拉起且 SSL 证书校验通过;启动失败时日志里会有原因。
docker-compose logs -f -
5配置 API Key
浏览器打开 Web UI,在 API Key 页面填核心 API(需支持 Realtime API,推荐阿里云)与辅助 API(ChatCompletion)。
-
6可选:用 Docker Run
不想用 Compose 时可用官方 docker run 命令,记得先创建 neko-network 网络,路径按需改成自己的。
NEKO_BASE_PATH="/home/neko/neko-data" && \ docker network create --driver bridge neko-network 2>/dev/null || true docker run -d \ --name neko \ --restart unless-stopped \ -p 48911:80 \ -p 48912:443 \ -v "${NEKO_BASE_PATH}/neko-home:/home/neko" \ -v "${NEKO_BASE_PATH}/logs:/app/logs" \ --network neko-network \ docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
NEKO_CORE_API_KEY | 是 | 核心 API 密钥,供实时语音对话使用,须支持 Realtime API | sk-xxxxxxxx |
NEKO_ASSIST_API_KEY_QWEN | 否 | 辅助 API(记忆/情感/视觉等)的阿里云百炼密钥 | sk-xxxxxxxx |
NEKO_CORE_API | 否 | 核心 API 提供商选择,默认 qwen | qwen |
NEKO_ASSIST_API | 否 | 辅助 API 提供商选择,默认 qwen | qwen |
NEKO_VISION_MODEL | 否 | 视觉理解模型名称,默认 qwen3-vl-plus-2025-09-23 | qwen3-vl-plus-2025-09-23 |
DISABLE_SSL | 否 | 设为 1 可临时禁用 SSL 校验;证书校验失败时可应急使用 | 0 |
如何确认成功
浏览器访问 http://localhost:48911 能打开 Web UI(API Key 页为 /api_key),且 docker-compose logs -f 无报错。
常见问题
Q:48911 端口被占用怎么办?
A:修改 docker-compose.yml 中的端口映射,把宿主机侧的 48911/48912 换成其他端口后重新 docker-compose up -d。
Q:容器启动失败怎么排查?
A:先 docker-compose logs -f 看原因;若是镜像拉取问题,可在 docker-compose.yml 中改用备用镜像源,再用 docker stats neko 查看资源占用。
Q:自定义 SSL 证书有什么要求?
A:必须为 PEM 格式、证书与私钥匹配、私钥无密码保护且在有效期内;容器启动时会自动校验,校验失败则容器启动失败。
Q:环境变量在 .env 里配了却不生效?
A:README 提示部分环境变量在源代码中可能无效,建议优先在 Web UI 中配置;用 .env 时以 docker-compose --env-file .env up -d 启动。
注意事项
- 容器内应用用户固定为 uid/gid 1000,neko-home/ 在宿主机上属主就是你,备份、编辑、删除都无需 sudo。
- 首次启动会自动生成有效期 1000 年的自签名证书,存放在挂载目录下的 ./neko-home/ssl/。
- README 建议优先在 Web UI 中配置 API 与服务商,环境变量中部分项可能无效。
- 若改用源码本地安装,需 Node.js >= 20.19 构建前端,并用 uv sync 安装依赖后启动 main_server 与 memory_server。
核心亮点
- 主动式交互:猫娘会先发起对话,而非被动等待指令
- 情感引擎驱动:模拟情绪变化,互动更自然有温度
- 数据自主可控:用户拥有数据,隐私更安全
不足之处
- 文档/社区待观察
- 3D 渲染和实时交互对硬件性能有一定要求
适用场景
- 个人桌面陪伴与日常聊天
- 作为智能助理管理日程、提醒和媒体分享
- 二次元风格数字人直播或内容创作
替代项目
Live2DViewerEX、VTuber Studio、Digital Human (如微软小冰)
同类项目推荐
busabase
开源
给 AI 智能体一个可自托管、带人工审核的数据库工作台
Open-source database & workspace for AI agents — structured data, durable knowledge···
interview-coach-agent-framework
开源
用多智能体模拟面试官,提前把面试练一遍
Interview coach application using Microsoft Agent Framework | https://aka.ms/mafinte···
MineLand
开源
在 Minecraft 里模拟数百个有感官和需求的智能体互动
Simulating Large-Scale Multi-Agent Interactions with Limited Multimodal Senses and P···
automata
开源
让 AI 自动写代码、改代码,你只负责验收
Automata: A self-coding agent
Wireshark-MCP
开源
丢个 pcap 包,用大白话问 AI,拿 tshark 真实数据答你
Wireshark-MCP,Give your AI assistant a packet analyzer. Drop a .pcap file, ask ques···
ai-science-toolkit
开源
让气候科学家用 AI 智能体自动搞定文献综述和代码审查
Skills & reviewer agents for AI-first climate science — built and used by a PhD atm···
gemini-cli
开源
在终端里喊一声 Gemini,它帮你读代码、跑命令、改文件,活儿直接干完。
An open-source AI agent that brings the power of Gemini directly into your terminal.
devo
开源
一套运行时,自由接入 DeepSeek/Qwen 等模型,本地智能编码
A self-improving agent. Tested on DeepSeek, Qwen, Kimi, GLM models. Supports MCP, S···
forkprobe
开源
同任务对比多个AI技能,快速选出最优解
Compare multiple skills on the same task and pick the winner.
