住宅主机Docker Compose一键启动NewAPI网关

准备工作：住宅主机的Docker环境

在住宅主机（无论是一台旧PC、NAS还是云服务器）上使用Docker Compose之前，需要先确保安装了Docker引擎和Docker Compose插件。
如果使用的是Linux系统（如Ubuntu、Debian、CentOS），推荐通过官方脚本安装Docker：

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

安装完成后，退出并重新登录当前用户，使组权限生效。
接着验证Docker是否安装成功：

docker --version  # 应显示Docker版本号
docker compose version  # 应提示“Docker Compose version v2.x.x”

如果没有 docker compose 命令，请执行 sudo apt install docker-compose-plugin（Debian/Ubuntu）或 sudo yum install docker-compose-plugin（CentOS/RHEL）。

编写 NewAPI 网关的 docker-compose.yml 文件

在你的住宅主机上，新建一个文件夹用于存放网关的配置：

mkdir ~/newapi-gateway && cd ~/newapi-gateway

创建一个名为 docker-compose.yml 的文件，内容如下（示例使用最新稳定版镜像，请先到 Docker Hub 搜索 newapi-gateway 确认镜像名）：

version: '3.8'

services:
  newapi-gateway:
    image: yourregistry/newapi-gateway:latest   # 请替换为实际镜像
    container_name: newapi-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"          # 宿主机端口:容器端口，根据需要修改
    environment:
      - TZ=Asia/Shanghai      # 时区设置
      # 根据NewAPI文档添加其他环境变量，如数据库连接等
    volumes:
      - ./config:/app/config  # 持久化配置文件
      - ./logs:/app/logs      # 持久化日志

注意：image 字段必须填写 NewAPI 网关官方提供的正确镜像名和标签。如果住宅主机需要访问外部网络，请确保网络通畅。

一键启动与状态检查

在 ~/newapi-gateway 目录下执行以下命令启动服务：

docker compose up -d

-d 参数表示后台运行。
等待几秒后，检查容器是否正常运行：

docker compose ps

若显示 State: Up，则说明启动成功。
你也可以通过 docker logs newapi-gateway 查看实时日志，确认无异常报错。

避坑指南：端口冲突与数据持久化

端口冲突： 如果住宅主机上的 8080 端口已被占用，
修改 docker-compose.yml 中的 ports 映射，
例如改为 “9090:
8080”，
之后访问 http:
//住宅主机IP:
9090。

数据持久化： 建议将配置和日志目录挂载到宿主机，这样容器删除或升级后数据不会丢失。
注意：宿主机上的 ./config 和 ./logs 目录必须先存在（可手动 mkdir），否则 Docker 会自动以 root 权限创建，导致权限问题。
推荐创建后修改其所有者：

mkdir config logs
sudo chown 1000:1000 config logs  # 假设容器内用户 UID 1000

高频问题与验证方法

Q：启动后无法访问管理页面？
检查防火墙是否放行了映射端口（如 8080）。如果住宅主机有 UFW 防火墙，执行 sudo ufw allow 8080。另外，查看容器日志 docker logs newapi-gateway，确认网关是否正常监听。

Q：如何更新网关版本？
进入目录后执行：

docker compose pull
docker compose up -d

验证网关是否正常工作： 在浏览器输入 http://住宅主机IP:8080（或你映射的端口），如果看到 NewAPI 网关的登录界面或健康检查页面，说明部署成功。
你还可以用 curl 测试接口：

curl -I http://localhost:8080/health

如果返回 200 OK，即可放心使用。

---

完成以上步骤后，你的住宅主机已经通过 Docker Compose 一键启动了 NewAPI 网关。
后续可以根据业务需求，配置路由、限流、认证等功能。
如果遇到其他异常，优先检查 docker-compose.yml 中的镜像版本和网络设置，或者查阅 NewAPI 官方文档。