# macOS 安装说明

# macOS 安装说明

## 系统要求

- macOS 10.13 (High Sierra) 或更高版本

- Intel 芯片（x86_64）或 Apple Silicon（M1/M2/M3/M4）

- 至少 100MB 可用磁盘空间

- 网络连接（用于访问设备网关）

---

直接下载预编译版本

### 1. 下载程序

从发布页面下载对应架构的压缩包：

- **Intel 芯片 Mac**：下载 `sensor-monitor-darwin-amd64.tar.gz`

- **Apple Silicon（M1/M2/M3/M4）**：下载 `sensor-monitor-darwin-arm64.tar.gz`

> 不确定芯片类型？点击左上角  →「关于本机」，查看「芯片」一项。

### 2. 解压

双击 `.tar.gz` 文件解压，或使用终端：

```bash

cd ~/Downloads

tar -xzf sensor-monitor-darwin-arm64.tar.gz

```

### 3. 移除隔离属性（解除 macOS Gatekeeper 拦截）

由于程序未经过 Apple 公证，首次运行前需要执行：

```bash

sudo xattr -rd com.apple.quarantine sensor-monitor

```

### 4. 运行程序

```bash

cd ~/Downloads

./sensor-monitor

```

看到类似以下输出表示启动成功：

```

[INFO] 服务器启动成功，监听端口 :8080

[INFO] 访问地址: http://localhost:8080

```

### 5. 访问系统

打开浏览器访问：`http://localhost:8080`

---

## 配置文件

程序首次启动会自动在当前目录生成 `config.yaml` 配置文件。按需修改后重启程序生效。

主要配置项：

```yaml

port: 8080                    # Web 服务端口

database: sensor_data.db      # 数据库文件路径

log_level: info               # 日志级别

```

---

## 使用串口设备（如需要）

如果连接的是 RS485 串口设备，macOS 需要安装串口驱动：

### 1. 安装驱动

- **CH340 芯片**：下载安装 https://github.com/WCHSoftGroup/ch34xser/blob/master/mac/CH34xVCPDriver-V1.5.zip

- **CP2102 芯片**：下载安装 https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers

- **FT232 芯片**：下载安装 https://ftdichip.com/drivers/vcp-drivers/

### 2. 查看串口设备名

插入串口转换器后，查看设备名：

```bash

ls /dev/cu.*

# 常见设备名: /dev/cu.usbserial-1420、/dev/cu.SLAB_USBtoUART 等

```

### 3. 在配置文件中填写串口设备名

```yaml

servers:

  - name: "串口网关"

    connection_type: serial

    serial_device: "/dev/cu.usbserial-1420"

    baud_rate: 9600

    data_bits: 8

    stop_bits: 1

    parity: "N"

```

### 4. 权限问题

如果提示权限不足，执行：

```bash

sudo chmod 666 /dev/cu.usbserial-*

```

---

## 后台常驻运行（launchd 服务）

创建服务文件：

```bash

sudo nano /Library/LaunchDaemons/com.sensor-monitor.plist

```

填入以下内容（请替换路径和用户名）：

```xml

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>Label</key>

    <string>com.sensor-monitor</string>

    <key>ProgramArguments</key>

    <array>

        <string>/Users/你的用户名/sensor-monitor/sensor-monitor</string>

    </array>

    <key>WorkingDirectory</key>

    <string>/Users/你的用户名/sensor-monitor</string>

    <key>RunAtLoad</key>

    <true/>

    <key>KeepAlive</key>

    <true/>

    <key>StandardOutPath</key>

    <string>/Users/你的用户名/sensor-monitor/output.log</string>

    <key>StandardErrorPath</key>

    <string>/Users/你的用户名/sensor-monitor/error.log</string>

</dict>

</plist>

```

加载服务：

```bash

sudo launchctl load /Library/LaunchDaemons/com.sensor-monitor.plist

```

管理服务：

```bash

# 停止服务

sudo launchctl unload /Library/LaunchDaemons/com.sensor-monitor.plist

# 查看日志

tail -f ~/sensor-monitor/output.log

tail -f ~/sensor-monitor/error.log

```

---

## 交叉编译（在其他平台编译 macOS 版本）

### 在 Windows 上编译 macOS 版本

```powershell

# Apple Silicon

$env:GOOS="darwin"

$env:GOARCH="arm64"

$env:CGO_ENABLED="1"

go build -o sensor-monitor-darwin-arm64 .

# Intel

$env:GOARCH="amd64"

go build -o sensor-monitor-darwin-amd64 .

```

### 在 Linux 上编译 macOS 版本

```bash

# Apple Silicon

CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o sensor-monitor-darwin-arm64 .

# Intel

CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o sensor-monitor-darwin-amd64 .

```

> **注意**：交叉编译需要安装 C 交叉编译工具链（因 SQLite 依赖 CGO）。

> - 编译 darwin/arm64 需要 `x86_64-apple-darwin-clang` 或使用 `osxcross`

> - 如无法配置交叉编译工具链，建议在 macOS 上直接编译

---

## 常见问题

### Q: 提示「无法打开，因为无法验证开发者」

```bash

sudo xattr -rd com.apple.quarantine /路径/sensor-monitor

```

或在「系统设置」→「隐私与安全性」中点击「仍要打开」。

### Q: 提示端口被占用

修改 `config.yaml` 中的 `port` 字段为其他端口（如 8081），或结束占用端口的进程：

```bash

lsof -i :8080

kill -9 <PID>

```

### Q: 串口设备找不到

1. 确认驱动已安装

2. 拔插 USB 重新识别

3. 检查设备名：`ls /dev/cu.*` 和 `ls /dev/tty.*`

### Q: 数据库文件在哪

数据库文件 `sensor_data.db` 位于程序运行目录下。备份数据库只需复制此文件。

---

## 卸载

1. 停止程序运行（`Ctrl+C` 或停止 launchd 服务）

2. 删除程序文件和配置文件：

```bash

cd ~

rm -rf sensor-monitor/

rm -f sensor_data.db config.yaml

```

3. 如使用了 launchd 服务：

```bash

sudo launchctl unload /Library/LaunchDaemons/com.sensor-monitor.plist

sudo rm /Library/LaunchDaemons/com.sensor-monitor.plist

```