NULI 在线电台｜服务器与本地部署

张宁的个人博客2026-08-28阅读 12业余无线电

以下内容供希望自行搭建站点的用户参考。普通访客无需执行这些步骤。
> ![|30](https://imgs.zgc261.com/blog/2026/10/hA8dr3FwnBY7.png) https://github.com/zgc261/Nuli-Radio

![](https://imgs.zgc261.com/blog/2026/10/sKc9vNLGqoZ3.png)
## 1. 准备环境

- 支持 PHP 的 Web 服务器，例如 Nginx + PHP-FPM 或 Apache + PHP。
- 当前接口代码按 PHP 7.4 及以上兼容编写；正式部署应使用仍获得安全维护、并通过项目验证的 PHP 版本，不必沿用旧服务器版本。
- 启用 PHP cURL 扩展；账号接口需要会话、JSON、密码散列和文件读写等能力。
- 不需要 MySQL，账号工作区使用服务器上的 JSON 文件保存。
- 服务器需要能访问外部目录接口；收听设备本身也需能连接音频源。

## 2. 构建 HTTP 版

获取完整项目后，在项目根目录执行：

```bash
python Radio/scripts/build-http.py
```

如果电脑上的 Python 命令为 `python3`，则改用：

```bash
python3 Radio/scripts/build-http.py
```

生成结果位于 `dist_radio/`。Python 用于构建，线上运行主要依靠浏览器及 PHP，不要求服务器常驻 Python。

## 3. 上传站点文件

将 **`dist_radio` 文件夹内部的全部内容** 上传到网站根目录，保持原有相对路径。不要只上传 `index.html`，也不要误多套一层目录。

关键文件包括：

```text
网站根目录/
├── index.html
├── app.js、其他 JS 和 CSS 文件
├── cloud-api.php
├── cloud-seed.json
├── radio-browser.php
└── covers/
```

`cloud-api.php` 提供账号与数据保存，`radio-browser.php` 提供目录查询转发。服务器必须执行 PHP，而不是把 PHP 源文件作为静态内容返回。

## 4. 设置私有数据目录

账号、会话和工作区数据必须存放在网站公开根目录之外，并允许 PHP 进程读写。

例如：

```text
/srv/nuli-radio/web/       网站根目录，放 dist_radio 的内容
/srv/nuli-radio/private/   私有数据目录，不对外提供下载
```

在 PHP-FPM 或站点运行环境中设置：

```text
NULI_RADIO_PRIVATE_DIR=/srv/nuli-radio/private
```

采用 PHP-FPM 时，应确保该变量传入运行站点的 PHP 进程；只在 SSH 终端设置，不一定对 PHP-FPM 生效。若启用 `open_basedir`，也需允许 PHP 访问此私有目录。

Linux 权限示例（将 `www-data` 改为实际 PHP 用户）：

```bash
sudo mkdir -p /srv/nuli-radio/private
sudo chown www-data:www-data /srv/nuli-radio/private
sudo chmod 750 /srv/nuli-radio/private
```

不应使用 `777`，也不要把私有目录映射成可公开下载的网页目录。项目会校验私有目录不能位于当前网站根目录内。

## 5. 首次启用账号

接口首次运行时自动创建维护者账号。初始登录方式请查看源码包内的 `CLOUD-SETUP.md`；维护者首次登录后必须修改密码。**应在站点开放给其他人之前完成首次改密**，不要把维护者账号作为普通访客账号分享。

此版本采用 HTTP，账号密码及会话传输不加密，请使用独立密码。若自行改为 HTTPS，需同时处理 HTTP 音频的混合内容限制，不能认为配置证书后所有旧源都能继续播放。

## 6. 上线检查与备份

- 检查首页、封面、分类、手机布局及多个直播源。
- 测试游客收藏，并刷新确认本地保存。
- 测试维护者登录、首次改密、修改、保存和重新加载。
- 测试全球目录；目录失败与音频源失败要分别排查。
- 备份整个私有目录。`workspace.json` 是工作区，`previous.json` 是上一版快照，但不能代替独立备份。
- 更新网页时保留私有目录，不要为升级页面删除账号和工作区文件。

音频由浏览器直接连接第三方源，目录转发接口并不代理音频。即使服务器可以访问某个源，也不代表访问者的网络可以播放。

## 7、如果部署在本地电脑，哪些功能不可用？

**区别主要在于运行方式，而不是“本地电脑”本身。** 本地运行 PHP 时，大部分后端功能仍可使用；仅运行静态服务器时，没有账号保存和服务器目录转发能力。

| 功能 | 直接双击 HTML（file://） | 本地静态 HTTP 服务 | 本地 PHP 服务 |
| --- | --- | --- | --- |
| 基本页面与分类 | 部分功能可能受限制，不推荐 | 可用 | 可用 |
| 在线电台播放 | 取决于文件页面限制及音频源 | 可用，仍需联网及源兼容 | 可用，仍需联网及源兼容 |
| 自定义源、收藏、本地保存 | 本地存储行为不稳定，不作为支持方式 | 可用 | 可用 |
| JSON 导入／导出 | 可能受浏览器限制 | 可用 | 可用 |
| 维护者登录与后端保存 | 不可用 | 不可用 | 可用，需配置私有目录与权限 |
| 服务器目录转发 | 不可用 | 不可用 | 可用，需 cURL 及外部网络 |
| 全球目录直接查询 | 不保证，受网络及浏览器限制 | 可能可用，受跨域和网络限制 | 可先尝试同站转发，仍受网络限制 |
| 其他设备共享账号数据 | 不可用 | 不可用 | 仅在其他设备能访问此电脑服务时可用 |

## 方式 A：仅体验页面和收听，运行静态服务

在项目根目录执行：

```bash
python -m http.server 8080 --bind 127.0.0.1 --directory dist_radio
```

打开：

```text
http://127.0.0.1:8080/
```

这种方式适合个人收听、测试布局、自定义源、收藏及备份。Python 静态服务器不执行 PHP，**账号登录、后端保存和 PHP 目录转发不可用**。全球目录可能尝试浏览器直连，但不能保证成功。请保持仅本机访问，不要将包含 PHP 文件的静态服务暴露给公网。

## 方式 B：需要账号保存，运行本地 PHP 服务

电脑需安装可用的 PHP。Windows PowerShell 示例，在项目根目录执行：

```powershell
$env:NULI_RADIO_PRIVATE_DIR = Join-Path (Get-Location) 'radio-private'
php -S 127.0.0.1:8080 -t dist_radio
```

macOS／Linux 示例：

```bash
NULI_RADIO_PRIVATE_DIR="$PWD/radio-private" php -S 127.0.0.1:8080 -t dist_radio
```

同样访问 `http://127.0.0.1:8080/`。私有目录位于 `dist_radio` 之外，需允许当前运行用户写入；目录转发还需要 PHP cURL 扩展。

此时账号保存到这台电脑，并不会自动同步到公网部署的另一套站点。PHP 内置服务器用于本地开发与体验，不建议作为公网正式服务。

## 8. 本地使用还要注意

1. **离线不能收听网络直播。** 本地部署只是页面和后端在本机，不会把电台节目下载到电脑。
2. **手机的 127.0.0.1 指向手机自己。** 上述命令仅监听本机，手机无法访问；局域网共享需要另行设置监听地址、防火墙及访问控制。
3. **电脑关机或服务停止后，其他设备无法访问。** 本地 PHP 服务不能提供脱离电脑运行的持续同步。
4. **本地和公网是两套数据。** 换域名、协议或端口，游客数据也可能不同，迁移请使用备份或明确的数据迁移方式。
5. **添加到主屏幕不等于离线 App。** 当前 HTTP 版本不会在非安全来源注册 Service Worker，不能承诺离线运行或安装后无限制后台播放。

发表评论让交流带来新的灵感

一	二	三	四	五	六	日
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31