企业官网建设流程全解析

• 网络安全

Portmaster 是 Safing 出品的隐私保护软件，而desktop/angular目录承载其全新的桌面端用户界面。本文以仓库中的 desktop/angular/README.md 为核心，结合仓库源码，完整讲解该 Angular 前端在 Ubuntu 上的本地搭建流程（含 Docker 方式）、开发目录结构、常用 CLI 命令（ng serve/ng build/ng test/ng e2e）以及与 Portmaster 核心服务（127.0.0.1:817API）的联通原理。读完本文，你可以独立在新环境上跑起这套 UI，并具备直接上手二次开发的完整路径。

项目概览：基于 Angular 的全新 Portmaster 用户界面

新 Portmaster UI 基于 Angular 实现，并使用@angular/cli完成构建、单元测试（Karma）与端到端测试（Protractor）。从仓库根目录的 desktop/angular/package.json 可以看到，项目基于 Angular 16（@angular/*依赖均为^16.0.1），同时引入了@fortawesome图标库、ng-zorro-antd组件库、d3/topojson-client（用于地图与数据可视化，对应 SPN 网络地图）、ngx-markdown与prismjs（文档渲染）、tailwindcss（样式体系）、fuse.js（模糊搜索）等关键依赖。

一个值得注意的设计是：这套 UI 可以与旧版 UI并行运行，因此当新界面尚有缺失或缺陷时，用户可以随时切换回旧界面。这也意味着新 UI 是作为独立的开发分支/模块存在，并不破坏既有可用性。

本地运行：在 Ubuntu 上搭建开发与测试环境

README 建议在 Ubuntu 机器上（虚拟机或裸机均可）准备工具链，然后用 Docker 化方式构建和测试新 UI。完整步骤如下。

1. 准备 Docker 工具链

sudo apt update sudo apt install -y docker.io git sudo systemctl enable --now docker sudo gpasswd -a $USER docker

安装并启动 Docker 服务后，将当前用户加入docker组，之后执行docker命令便无需sudo（需重新登录会话使组变更生效）。

2. 安装 Portmaster 并启用开发配置

新 UI 依赖本机正在运行的 Portmaster 核心服务提供数据与事件推送。请先通过官方.deb安装包安装 Portmaster，然后为服务注入两个关键的启动参数：

echo 'PORTMASTER_ARGS="--experimental-nfqueue --devmode"' | sudo tee /etc/default/portmaster sudo systemctl daemon-reload sudo systemctl restart portmaster

其中：

• --experimental-nfqueue：启用基于 Linux nfqueue 的实验性包拦截路径；
• --devmode：开发者模式，放开开发调试相关的接口与行为限制。

这两个参数通过/etc/default/portmaster环境文件注入 systemd 服务，重启后生效。

3. 构建并运行新 UI（Docker 方式）

# Clone the repository git clone https://github.com/safing/portmaster-ui # Enter the repo and checkout the correct branch cd portmaster-ui git checkout feature/new-ui # Enter the directory and run docker.sh cd modules/portmaster sudo bash ./docker.sh

脚本执行完成后，在浏览器中访问http://localhost:8080即可看到新 UI。

说明：README 中的路径与分支对应的是该项目早期的开发形态（独立仓库portmaster-ui的feature/new-ui分支）。在当前仓库中，对应代码已合并至 desktop/angular 目录，你可以直接在仓库根目录执行cd desktop/angular && sudo bash ./docker.sh完成同样的操作。

来看仓库中 desktop/angular/docker.sh 的实现，脚本逻辑非常精简——它只是一个 Docker 封装器：

#!/bin/bash # cd to script dir baseDir="$( cd "$(dirname "$0")" && pwd )" cd "$baseDir" # get base dir for mounting mnt="$( cd ../.. && pwd )" # run container and start dev server docker run \ -ti \ --rm \ -v $mnt:/portmaster \ -w /portmaster/desktop/angular \ -p 8081:8080 \ node:latest \ npm start -- --host 0.0.0.0 --port 8080

关键点解读：

• 以官方node:latest镜像为基础，无需在宿主机安装 Node.js/npm；
• 通过-v把仓库根目录（脚本向上两级目录）挂载到容器内/portmaster，开发源码与容器实时共享，改动即时可见；
• 工作目录设为容器内的/portmaster/desktop/angular；
• 端口映射为8081:8080，即容器内 dev server 监听0.0.0.0:8080，宿主机访问http://localhost:8081即可（README 中写http://localhost:8080对应的是直接指定端口映射为8080:8080的早期脚本版本）；
• 容器内执行npm start（见下文 npm scripts 说明），并显式传入--host 0.0.0.0 --port 8080以允许容器外部访问。

Hacking Quick Start：本地开发环境配置

Docker 方式虽开箱即用，但 README 明确指出，为了获得最佳开发体验，推荐在宿主机本地安装@angular/cli。此外还建议使用 VSCode（或其 OSS / 服务端变体），并安装以下扩展：

• Angular Language Service（官方）：提供模板类型检查、智能补全与诊断；
• Tailwind CSS Extension Pack：项目使用 Tailwind CSS 3（见 desktop/angular/tailwind.config.js 与 package.json 中tailwindcss: ^3.3.2依赖），该扩展提供类名提示与格式化；
• formate: CSS/LESS/SCSS formatter：由于项目同时使用 SCSS（src/app下组件样式默认scss，见 angular.json 中"style": "scss"的 schematics 配置）与 LESS（src/theme.less、src/theme.less），该格式化器可统一处理。

目录结构：从项目根到应用源码

README 明确了两个核心目录：

• src/：实际应用源码；
• e2e/：端到端测试源码。

其中src/下的组织结构，与当前仓库 desktop/angular/src 的实际情况完全对应：

另外值得补充的是，仓库在src/app之外还以 Angular workspace 的方式维护了多个 library 项目（desktop/angular/projects 目录）：safing/（@safing/ui与@safing/portmaster-api内部库）、portmaster-chrome-extension/（浏览器扩展构建目标）与tauri-builtin/（Tauri 桌面壳构建目标，见 package.json 中@tauri-apps/*依赖）。

开发服务器与 API 联通原理

ng serve开发服务器

运行ng serve启动开发服务器，访问http://localhost:4200/，修改源文件后应用会自动热重载。但直接使用ng serve时，开发服务器默认只监听localhost，且 README 强调：在开发模式（未传--prod）下，UI 期望 Portmaster 运行在ws://127.0.0.1:817/api/database/v1。

这一点可以从 desktop/angular/src/environments/environment.ts 得到源码级印证：

export const environment = { production: false, portAPI: "ws://127.0.0.1:817/api/database/v1", httpAPI: "http://127.0.0.1:817/api", supportHub: "https://support.safing.io" };

而生产环境 desktop/angular/src/environments/environment.prod.ts 则改为动态取当前主机：

export const environment = { production: true, portAPI: `ws://${window.location.host}/api/database/v1`, httpAPI: `http://${window.location.host}/api`, supportHub: "https://support.safing.io" };

对应的服务端事实是：Portmaster 核心服务默认将 API 监听在127.0.0.1:817，定义见 service/core/base/module.go（var DefaultAPIListenAddress = "127.0.0.1:817"）。也就是说：

• 开发模式：前端 WebSocket 直连本机 Portmaster 的数据库订阅端点ws://127.0.0.1:817/api/database/v1；
• 生产模式：前端由 Portmaster 服务端同源托管（base-href 为/ui/modules/portmaster/，见 package.json 的build脚本），因此 API 地址动态取自页面所在主机。

npm scripts：比 README 更完整的开发命令

README 只列了ng serve，而当前仓库 desktop/angular/package.json 的 scripts 字段提供了更丰富的命令，这里一并整理：

其中proxy.json的作用值得单独说明。仓库中的 desktop/angular/proxy.json 内容为：

{ "/api": { "target": "http://localhost:817/", "secure": false } }

也就是说，当通过npm start/npm run serve启动时，ng serve会把所有/api/*请求代理转发到本机 Portmaster 的http://localhost:817/，从而规避开发模式下的跨域问题；而 WebSocket 数据通道则直接由environment.portAPI指向ws://127.0.0.1:817/api/database/v1。

代码脚手架：快速生成组件与模块

运行ng generate component component-name生成一个新组件；也可以使用其他生成器：

ng generate directive|pipe|service|class|guard|interface|enum|module

配合 angular.json 中的 schematics 默认配置（组件样式默认scss、应用为strict严格模式），新生成的代码会自动遵循项目的编码规范。由于 UI 采用模块化组织（layout/、pages/、services/、shared/、widgets/），生成组件后按功能归类到对应目录即可。

构建、单元测试与端到端测试

构建产物

运行ng build构建项目，构建产物输出到dist/目录（该路径在 angular.json 的outputPath中定义）。使用--prod标志进行生产构建——在当前 Angular 16 版本中，等价写法是ng build --configuration production，并会通过fileReplacements机制将environment.ts替换为environment.prod.ts。

对于正式发布场景，建议直接使用npm run build：它会先以 production 配置构建@safing/ui与@safing/portmaster-api两个内部库，再执行带/ui/modules/portmaster/base-href 的应用生产构建，产物可被 Portmaster 服务端 UI 模块直接托管（对应 service/ui 的静态资源服务）。

单元测试

运行ng test通过 Karma 执行单元测试。仓库中已经具备一定规模的测试覆盖，例如：

• 组件级测试：app.component.spec.ts；
• 服务级测试：notifications.service.spec.ts、status.service.spec.ts；
• src/下的test.ts是 Angular CLI 生成的 Karma 测试入口。

端到端测试

运行ng e2e通过 Protractor 执行端到端测试，测试源码位于 desktop/angular/e2e 目录。E2E 测试会驱动真实浏览器验证完整用户流程，适合在本地跑通 UI 后做回归验证。

更多帮助

如需了解更多 Angular CLI 用法，运行ng help查看内置帮助，或查阅 Angular CLI 官方 README（README 中指向https://github.com/angular/angular-cli/blob/master/README.md）。

常见问题与排障要点

1. 浏览器访问不到 UI：若使用 Docker 方式，请确认docker.sh中-p端口映射与 README 的访问地址一致（当前仓库脚本为8081:8080，应访问http://localhost:8081）；若本地ng serve，访问http://localhost:4200/。
2. UI 空白或数据不刷新：确认 Portmaster 服务已以--devmode启动并监听127.0.0.1:817（PORTMASTER_ARGS配置后务必systemctl daemon-reload && systemctl restart portmaster）。
3. 跨域报错：使用npm start/npm run serve（带proxy.json）启动 dev server，让/api请求走代理；WebSocket 直连按环境变量portAPI配置自动处理。
4. 内部库（@safing/ui、@safing/portmaster-api）报错：先执行npm run build-libs:dev或npm start（内部已包含该步骤），因为应用构建依赖这些库的最新产物。
5. 新 UI 与旧 UI 并行：两者可同时运行，若新 UI 某功能缺失或异常，随时切回旧界面，不影响 Portmaster 核心功能。

小结

Portmaster 的 Angular UI 是一个完整的 Angular 16 workspace 应用，既支持 Docker 一键起服务（docker.sh挂载源码、Node 容器内运行），也支持宿主机本地开发（@angular/cli+ VSCode 扩展）。理解ws://127.0.0.1:817/api/database/v1这条 WebSocket 数据通道（前端 environment.ts ↔ 后端 service/core/base/module.go），是排查 UI 数据链路问题的关键。按本文步骤，你即可在新机器上完成环境准备、构建运行、代码生成与测试全流程，并在此基础上继续深入layout/、pages/、services/等模块做功能开发。

• 网络安全