配置文件

配置文件 config.yaml 只放启动之前就要知道的设置。大部分日常设置存在数据库里，在界面上改，见下文不在配置文件里的设置。

位置与生效

项	说明
路径	Docker 部署是 compose 目录下的 config/config.yaml，容器里为 /app/config/config.yaml。二进制部署由 -c 参数指定，默认是工作目录下的 config/config.yaml。界面「设置 › 关于」的「配置路径」显示当前用的是哪个文件。
格式	YAML。没写的键取默认值。
生效	改完要重启 nSIM。
写错的键	段内拼错的键被静默忽略。不认识的顶层段，启动时会打印一条「完全不生效」的提示。改完对照本页核对键名。
权限	文件里有口令，权限设为 600。文件和它所在的目录都要对 nSIM 可写，界面里改口令、添加设备时会写回这个文件。

界面改过就以界面为准的项

下面这些由配置文件给初值，之后在界面里改。

配置项	在界面里哪里改	改后
web.password	「设置 › 账号与安全」	以加密形式写回配置文件
web.two_factor	「设置 › 账号与安全」的「通知渠道验证码」	写回配置文件
devices、readers	「设备」页添加设备	写回配置文件
devices 里的选网、控制面后端	设备的「选网方式」、设备的「模组」页签	写回配置文件
github_mirror	「设置 › GitHub 下载加速」	存进数据库，此后配置文件里的这一段不再生效

不在配置文件里的设置

下面这些只存在数据库里，在界面上改，配置文件里没有对应的键：

• 卡策略，见卡策略。新卡默认是飞行模式。
• 所在地区，在「设置 › 设备接管」里改。
• 界面语言，存在各自的浏览器里，在「设置 › 外观」里改。
• 通知渠道、代理实例、出口节点与订阅。
• 短信转发和拦截规则、自动化脚本。
• 数据保留期限、API Key、身份验证器。

数据与日志的位置

没有配置项能改这些位置。它们都相对于工作目录，Docker 里工作目录是 /app。要放到别的盘上，就把目录挂载或链接过去。

路径	内容
data/nsim.db	数据库：设备、卡策略、短信、通话记录等全部数据
data/backups/	定时自动备份的默认位置
logs/app.log	当天的应用日志，指向 logs/app-<日期>.log

server

键	作用	默认值	何时需要改
port	管理界面监听的端口。写 7575 或 ":7575" 都表示所有网卡；写 "127.0.0.1:7575" 表示只在本机监听。	7575	端口冲突时；放在同机的反向代理后面时改成只在本机监听。Docker 镜像的健康检查固定访问 7575，改端口后见打不开界面或登录不了。
debug	输出调试级日志。	false	排查问题时临时打开。
debug_domains	启动时就打开的调试域，逗号分隔，all 为全开。	空	只在排查启动阶段的问题时用。运行中可在「诊断」页的日志里开关调试域。日志量会大增，排查完清空。

web

键	作用	默认值	何时需要改
username	管理界面的用户名。	admin	按需。
password	管理界面的口令，可写明文。在界面改过后，这里会变成加密后的哈希。	admin	第一次启动前必须改。忘了口令时，改成新的明文并重启。
two_factor.enabled	登录时经通知渠道发一次性验证码。	false	在界面里开即可。
two_factor.channel	发验证码用的通知渠道名，如 telegram、bark、email。	空	同上。渠道要先在「设置 › 通知」里配好。
two_factor.code_ttl_seconds	验证码有效期，秒。	300	一般不改。
two_factor.max_attempts	一次登录最多能试几次验证码。	5	一般不改。

口令是 admin 或 change-me 时，启动日志会打印「安全警告」。用它登录后必须先改密，见第一次登录与初始设置。

devices

已接管的模组，一台一项。一般不手写：在「设备」页添加设备后，nSIM 自己写进来。手写时只写身份，不写任何 /dev 路径。nSIM 每次都按 IMEI 重新查找设备，因为模组重启后设备文件常换编号。

键	作用	默认值	何时需要改
id	设备 ID，短信、通话记录都按它关联。	型号加 IMEI 后四位	创建后不要改。
name	界面上显示的名字。	空	随意。
modem_imei	模组的 IMEI，nSIM 靠它认出这台模组。	无	手写时必填。
device_backend	控制模组的方式：at、qmi 或 mbim。	at	在界面里切换。qmi、mbim 要与模组实际加载的驱动一致，否则设备起不来。
esim_transport	读写 eSIM 的通道：at、qmi 或 mbim。	at	一般不改。
mbim_transport	MBIM 控制口的打开方式：auto、proxy 或 direct。	auto	一般不改。
qmi_use_proxy	经 qmi-proxy 打开 QMI 控制口，让多个功能共用。	false	用 QMI 管理 eSIM 时建议打开。
qmi_proxy_path、qmi_proxy_executable	qmi-proxy 的套接字名与程序路径。	空，即 /usr/libexec/qmi-proxy	发行版把 qmi-proxy 装在别处时。
data_plane_mode	数据通路：native 或 qmap。qmap 能多承载一条连接，模组网卡名会从 wwan 开头变成 qmimux 开头。	native	不手写。卡策略需要时，nSIM 会自动改成 qmap。
at_sidecar	用 QMI 或 MBIM 控制时，另开一条 AT 通道，用于通话音频等。	true	出问题时可写 false 关闭。
operator_selection_mode	选网方式：automatic 或 manual。	automatic	在界面里改。
operator_selection_plmn	手动选网时的网络代码（MCC+MNC），如 46001。	空	在界面里改。
operator_selection_rat	手动选网时限定的制式：gsm、wcdma、lte 或 nr5g。	空，不限	在界面里改。
esim_switch.*	切换 eSIM 时的几项附加动作，全部默认关闭。	关闭	一般不改。
proxy_port	旧字段，设备列表里显示的代理端口。代理实例实际在「代理」页管理。	0	不用。
baud_rate、data_bits、stop_bits、parity	串口参数。AT 通道实际固定按 115200、8、1、N 打开。	115200、8、1、N	不用。

readers

已接管的 USB 读卡器，一个一项。一般不手写，在「设备」页添加。

键	作用	默认值	何时需要改
id	读卡器设备 ID，由卡的身份生成。	rd- 加卡号尾部	创建后不要改。
name	界面上显示的名字。	空	随意。
card	卡的身份：eSIM 填 EID，普通 SIM 填 ICCID。卡换到另一个读卡器，仍是同一台设备。	无	手写时必填。

vowifi

VoWiFi 是否开启不在这里，由每张卡的卡策略决定。

键	作用	默认值	何时需要改
device_profile.profile	VoWiFi 注册时对运营商声称的手机机型，取内置机型名。不认识的名字按内置默认机型处理。	内置默认	一般不改。
device_profile.manufacturer、model、android_version、build	自定义机型。四项同时填写才生效，否则仍用内置机型。	空	运营商只接受特定机型时。

sms

键	作用	默认值	何时需要改
suppress_binary	丢弃看起来是发给 SIM 卡本身的二进制短信。判断错一次，那条短信就收不到也不提醒。	false	一般不改。

roaming_guard

防止「飞行模式」和「VoWiFi」策略的卡在本地驻网。nSIM 会把这里的网络写进这类卡的禁止网络表，让卡在本地搜不到网。详见防止漫游产生费用。

键	作用	默认值	何时需要改
local_plmns	主机所在地运营商的网络代码（MCC+MNC）列表。卡里通常只有 4 格，放不下时优先保留排在前面的。	空，即关闭	想用这项防护时，写上当地运营商；主机搬到别的国家时跟着改。示例配置里预填了中国的 46000、46001、46011，主机不在中国时改掉或删掉。

usb_recovery

模组所在的 USB 端口卡死、模组掉出总线时，nSIM 会重置端口让它回来。

键	作用	默认值	何时需要改
disabled	关闭这项自救。	false，即开启	一般不改。
sysfs_write_root	写 sysfs 时用的替代根目录。	空，直接写 /sys	Docker 部署写 /hostsys，配合 compose 里挂载的 /sys/devices:/hostsys/devices。二进制部署留空。

log

键	作用	默认值	何时需要改
format	日志格式：text 或 json。	text	交给日志采集系统时用 json。
stdout	是否同时输出到标准输出。	true	二进制部署时 journald 和 logs/ 里各有一份。只想留一份时写 false，journald 里仍保留崩溃和启动早期的输出。
max_age_days	logs/app-*.log 保留的天数。nSIM 自己按天轮转，不要再用 logrotate 处理这些文件。	30	按需。
access_log	每个 HTTP 请求记一条访问日志。关着时仍记录出错的请求。	false	排查访问问题时临时打开。

backup

定时自动备份。用法见备份与恢复。

键	作用	默认值	何时需要改
enabled	开启定时自动备份。	false	建议开启。
interval_hours	两次备份的间隔，小时。启动后先等一个间隔再做第一份。	24	按需。
keep	保留最近几份，多出的删最旧的。	7	按需。
dir	备份存放的目录。	data/backups	指到另一块盘，才防得住硬盘损坏。
passphrase	非空时用它加密备份。口令丢了，备份就打不开。	空，不加密	备份要拷离主机时设置。

upstream_proxy

键	作用	默认值	何时需要改
allow_private_subscription	允许从本机或局域网地址导入节点订阅，也允许订阅里出现本机或局域网地址的节点。	false	只在订阅转换服务跑在本机或局域网里时打开。打开后，任何有代理写权限的 API Key 都能借 nSIM 访问你的内网。这一项只能在配置文件里改。

sip_gateway

让 Linphone 等 SIP 客户端接入 nSIM。用法见用 Linphone 接电话。账号密钥、推送设置在「语音 › 语音设置」里，不在这里。

键	作用	默认值	何时需要改
enabled	开启 SIP 网关。	false	要用 SIP 客户端时。
listen	监听的 IP 地址列表，如局域网地址和 VPN 地址各一个。不接受 0.0.0.0 或 ::。	空	开启时必填。
sip_port	信令端口，UDP 和 TCP 共用。	5060	端口冲突时。
rtp_port_min、rtp_port_max	通话声音用的端口范围。	31000、31999	端口冲突或防火墙规则需要时。
advertise_host	写进 SIP 客户端配置的服务器地址。	空，取 listen 的第一个	SIP 客户端要用别的地址连过来时。

yellow_pages

来电和短信旁显示机构名称用的号码目录。查号在本机完成，下载请求里不带任何号码。

键	作用	默认值	何时需要改
directory_enabled	下载并定期更新号码目录。关闭后已下载的照常使用。	true	不想让 nSIM 访问外网下载时。
directory_urls	下载地址，按顺序尝试。	空，用内置地址	用自建镜像时。
refresh_hours	更新周期，小时。	168	一般不改。

github_mirror

从 GitHub 下载文件时先经公共加速代理。在「设置 › GitHub 下载加速」里保存过之后，以界面为准，这一段不再生效。用法见加速从 GitHub 下载。

键	作用	默认值	何时需要改
enabled	开启加速。关闭时只直连 GitHub。	true	在界面里改。
prefixes	加速代理的前缀列表，按顺序尝试，形如 https://example.com/。	空，用内置列表	内置的都失效时。

carrier_config

nSIM 从网上下载各运营商的参数，用于 VoWiFi、VoLTE 等功能。请求里只带公开的网络代码，不上传卡号等信息。已下载的会缓存，离线时继续使用。

键	作用	默认值	何时需要改
urls	下载地址，按顺序尝试。	空，即 https://carrier.nsim.cc/	用自建镜像时。
refresh_hours	检查更新的周期，小时。	24	一般不改。
runtime	new 使用下载的运营商参数；legacy 不读下载的参数，只用内置的缺省值。	new	只在下载的参数导致问题、需要应急回退时改成 legacy。

命令行参数

参数	作用	默认值
-c <路径>	配置文件路径，相对路径按工作目录算。	config/config.yaml
-backend-only	只提供接口，不提供网页界面。	关闭

Docker 环境变量

变量	作用	默认值
TZ	日志使用的时区。	UTC
NSIM_PCSC_MODE	读卡器驱动从哪里来：auto 有主机的 PC/SC 服务就用主机的，否则用镜像自带的；system 只用主机的；bundled 只用镜像自带的。	auto

不要设置 HTTP_PROXY、HTTPS_PROXY。它们会把 nSIM 的全部出站请求塞进同一个代理，与 nSIM 按卡选择出口冲突。