用 Docker 安装

这一页带你在一台 Linux 主机上用 Docker Compose 跑起 nSIM。大多数人选这种方式；不想用 Docker 的，看用二进制文件安装。

开始之前

一台 Linux 主机，CPU 架构是 amd64、arm64 或 armv7。完整要求见支持的模组与主机。
主机上装好了 Docker 和 Compose 插件，能运行 docker compose。
至少一台模组已经用 USB 接到这台主机。在主机上执行下面的命令，应能列出至少一个 /dev/ttyUSB*：
终端窗口
```
ls /dev/ttyUSB* /dev/cdc-wdm*
```
一个都没有时，nSIM 也认不到模组，先看模组不出现或不识卡。
镜像地址：<发布地址待定>。

下面的命令都以 root 身份执行。

准备目录

mkdir -p /opt/nsim/config /opt/nsim/data /opt/nsim/logs
cd /opt/nsim

之后的文件都放在 /opt/nsim 下。

写 compose 文件

新建 /opt/nsim/docker-compose.yml，内容如下：

services:
  nsim:
    image: <发布地址待定>
    container_name: nsim
    restart: unless-stopped
    network_mode: host
    device_cgroup_rules:
      - 'c 188:* rwm'   # AT 串口，/dev/ttyUSB*
      - 'c 180:* rwm'   # QMI / MBIM 控制口，/dev/cdc-wdm*
      - 'c 189:* rwm'   # USB 读卡器
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - ./logs:/app/logs
      - /dev:/dev
      - /run/pcscd:/run/pcscd
      - /sys/devices:/hostsys/devices
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"
    environment:
      - TZ=Asia/Shanghai

每一项为什么这样写：

选项	为什么
`network_mode: host`	代理要把流量绑到具体的模组网卡上，容器必须直接看到主机网卡。因此不写 `ports:`，写了也不生效。
`device_cgroup_rules`	容器默认打不开模组的设备文件。放行这三类就够了，不需要 `privileged: true`。
`/dev:/dev`	模组重启后设备文件常换编号。只有挂载整个 `/dev`，容器才看得到新出现的节点。不要改成 `devices:` 列表。
`./config`、`./data`、`./logs`	配置、数据库和日志。挂目录，不要只挂 `config.yaml` 一个文件：nSIM 改配置时会整个替换这个文件。
`/run/pcscd`	主机上运行着 PC/SC 服务时，nSIM 借它访问读卡器。没有读卡器也可以留着。
`/sys/devices:/hostsys/devices`	模组所在的 USB 端口卡死时，nSIM 会重置端口自救。容器里的 `/sys` 是只读的，所以另挂一份可写的。
`logging`	Docker 默认不轮转容器日志，会一直增长到磁盘写满。
`TZ`	日志使用的时区，改成你所在的时区。

不要在 environment 里加 HTTP_PROXY 或 HTTPS_PROXY。nSIM 会按卡选择出口，这两个变量会把它的全部出站请求塞进同一个代理。

写配置文件

新建 /opt/nsim/config/config.yaml，写入下面几行：

server:
  port: 7575

web:
  username: admin
  password: 换成你自己的长口令

usb_recovery:
  sysfs_write_root: /hostsys

键	作用
`server.port`	管理界面的端口。和别的服务不冲突就保持 7575。
`web.username`、`web.password`	管理界面的账号和口令。口令可以写明文。
`usb_recovery.sysfs_write_root`	让 nSIM 通过 compose 里另挂的 `/hostsys` 重置 USB 端口。

文件里有口令，把权限收紧：

chmod 600 config/config.yaml

其余配置项都有默认值，需要时再查配置文件。

启动

docker compose up -d
docker compose logs -f

日志持续输出、容器没有反复重启，就说明在正常启动。按 Ctrl+C 退出日志，容器会继续运行。

日志开头出现「安全警告」时，说明口令还是出厂值。这条警告写着「Web 管理口令仍是出厂默认或示例文件里的占位值」。改好配置文件后，执行 docker compose restart。

完成后

在主机上执行：
终端窗口
```
curl -fsS http://127.0.0.1:7575/ready
```
返回 "status":"ok" 就是已就绪。启动后的一两分钟里会返回 503，checks 里的 startup 是 in_progress，稍等再试。
执行 docker ps。就绪后不到一分钟，nsim 一行的状态会变成 healthy。
在另一台电脑的浏览器里打开 http://<主机地址>:7575，能看到登录页。

/ready 一直不返回 ok，或别的电脑打不开登录页，看打不开界面或登录不了。