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"   # HTTP 访问端口
      - "48912:443"  # HTTPS 访问端口
    volumes:
      - ./N.E.K.O:/root/Documents/N.E.K.O
      - ./logs:/app/logs
      - ./ssl:/root/ssl
    networks:
      - neko-network
networks:
  neko-network:
    driver: bridge

启动命令：

docker-compose up -d

常用命令：

• 查看日志：docker-compose logs -f
• 停止服务：docker-compose down
• 重启服务：docker-compose restart

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}/N.E.K.O:/root/Documents/N.E.K.O" \
  -v "${NEKO_BASE_PATH}/logs:/app/logs" \
  -v "${NEKO_BASE_PATH}/ssl:/root/ssl" \
  --network neko-network \
  docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest

📁 目录结构

启动后会自动生成以下目录结构：

当前目录/
├── N.E.K.O/      # 配置文件和数据
├── logs/         # 应用日志
├── ssl/          # SSL证书
└── docker-compose.yml

自动证书

容器首次启动时会自动生成有效期为 1000 年 的自签名证书，证书文件保存在 ./ssl/ 目录。

自定义证书

如需使用自己的 SSL 证书：

方法一：启动前配置（推荐）

# 创建证书目录
mkdir -p ./ssl

# 放入您的证书文件（必须命名为特定名称）
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key

方法二：启动后替换

# 1. 停止容器
docker-compose down

# 2. 替换证书文件
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key

# 3. 重新启动
docker-compose up -d

证书要求

• ✅ 必须为 PEM 格式
• ✅ 证书和私钥必须匹配
• ✅ 私钥不能有密码保护
• ✅ 证书必须在有效期内
• ❌ 不支持加密的私钥

证书验证

容器启动时会自动验证 SSL 证书：

• ✅ 验证通过：正常启动 HTTPS
• ❌ 验证失败：容器启动失败，请查看日志
• ⚠️ 跳过验证：设置 DISABLE_SSL=1 可临时禁用 SSL

查看证书信息

docker exec neko openssl x509 -in /root/ssl/N.E.K.O.crt -noout -text

注意：部分环境变量在源代码中可能无效，建议优先在 Web UI 中配置。 在 docker-compose.yml 中取消 environment 部分的注释并按需配置：

environment:
  # API 密钥配置
  - NEKO_CORE_API_KEY=${NEKO_CORE_API_KEY}
  - NEKO_ASSIST_API_KEY_QWEN=${NEKO_ASSIST_API_KEY_QWEN}
  - NEKO_ASSIST_API_KEY_OPENAI=${NEKO_ASSIST_API_KEY_OPENAI}
  - NEKO_ASSIST_API_KEY_GLM=${NEKO_ASSIST_API_KEY_GLM}
  - NEKO_ASSIST_API_KEY_STEP=${NEKO_ASSIST_API_KEY_STEP}
  - NEKO_ASSIST_API_KEY_SILICON=${NEKO_ASSIST_API_KEY_SILICON}
  - NEKO_MCP_TOKEN=${NEKO_MCP_TOKEN}

  # API 提供商选择
  - NEKO_CORE_API=${NEKO_CORE_API:-qwen}
  - NEKO_ASSIST_API=${NEKO_ASSIST_API:-qwen}

  # 模型配置
  - NEKO_SUMMARY_MODEL=${NEKO_SUMMARY_MODEL:-qwen-plus}
  - NEKO_CORRECTION_MODEL=${NEKO_CORRECTION_MODEL:-qwen-max}
  - NEKO_EMOTION_MODEL=${NEKO_EMOTION_MODEL:-qwen-turbo}
  - NEKO_VISION_MODEL=${NEKO_VISION_MODEL:-qwen3-vl-plus-2025-09-23}

  # SSL 配置
  - SSL_DOMAIN=${SSL_DOMAIN:-project-neko.online}
  - SSL_DAYS=${SSL_DAYS:-365000}
  - DISABLE_SSL=${DISABLE_SSL:-0}
  - AUTO_REGENERATE_CERT=${AUTO_REGENERATE_CERT:-1}
  - NGINX_AUTO_RELOAD=${NGINX_AUTO_RELOAD:-1}

快速设置示例：

# 创建 .env 文件
cat > .env << EOF
NEKO_CORE_API_KEY=your_core_api_key_here
NEKO_ASSIST_API_KEY_QWEN=your_qwen_api_key
NEKO_MCP_TOKEN=your_mcp_token
SSL_DOMAIN=your-domain.com
EOF

# 启动时加载环境变量
docker-compose --env-file .env up -d

1. 端口冲突

# 检查端口占用
ss -tulpn | grep ':4891[12]'
# 解决方案：修改 docker-compose.yml 中的端口映射
# 例如：- "8080:80" 和 - "8443:443"

2. 权限问题

# 确保目录有正确权限
mkdir -p N.E.K.O logs ssl
chmod 755 N.E.K.O logs ssl

3. 容器启动失败

# 查看详细日志
docker-compose logs --tail=100

# 或直接查看容器日志
docker logs neko --tail=100

4. SSL 证书错误

# 删除错误证书，让容器重新生成
rm -f ssl/N.E.K.O.crt ssl/N.E.K.O.key
docker-compose up -d

5. 网络问题

# 检查网络连通性
curl -v http://localhost:48911/health
curl -v -k https://localhost:48912/health

6. 容器无法访问

# 检查容器状态
docker ps | grep neko

# 检查容器日志
docker logs neko

# 进入容器调试
docker exec -it neko bash

7. 磁盘空间不足

# 清理无用镜像
docker system prune -f

# 清理容器日志
docker-compose down && docker volume prune -f

8. 镜像拉取失败

# 尝试使用备用镜像源
# 在 docker-compose.yml 中将镜像改为：
# image: ghcr.io/project-n-e-k-o/n.e.k.o:latest

健康检查

# 检查服务健康状态
curl http://localhost:48911/health
curl -k https://localhost:48912/health

资源监控

# 查看容器资源使用
docker stats neko

# 查看容器进程
docker top neko

# 查看容器详细信息
docker inspect neko

日志管理

# 实时查看日志
docker-compose logs -f

# 查看最近100行日志
docker-compose logs --tail=100

# 查看错误日志
docker-compose logs | grep -i error

# 清理日志文件
docker-compose down
rm -rf logs/*.log
docker-compose up -d

数据备份

# 备份重要数据
tar -czf neko-backup-$(date +%Y%m%d).tar.gz \
  N.E.K.O/ \
  ssl/ \
  docker-compose.yml

版本升级

# 拉取最新镜像
docker-compose pull

# 重启服务
docker-compose up -d