# Runbook: Joplin — синк Mac ↔ телефон (WebDAV / Android-хотспот)

Симптом: **синхронизация перестала работать** между Joplin на Mac и на телефоне.

Стек: **rclone serve webdav** на Mac → `~/JoplinSync` → Joplin (Mac + Android) по HTTP. Облако Joplin не используется.

**Рабочая схема (2026-06, проверено):** Mac на **DHCP**, alias **`*.100`** на `en0`, телефон → `http://<подсеть>.100:8080`. Подробно: [STABLE_SETUP.md](./STABLE_SETUP.md).

---

## Архитектура

```
Телефон (Joplin)  ──HTTP──►  Mac en0 alias *.100:8080  ──►  rclone  ──►  ~/JoplinSync/
Mac (Joplin)      ──HTTP──►  127.0.0.1:8080 (тот же rclone)
```

| Компонент | Путь / имя |
|-----------|------------|
| Данные | `~/JoplinSync` |
| Учётка | `~/.config/joplin-webdav/env` (`600`, не в git) |
| WebDAV | LaunchAgent `com.eternal.joplin-webdav` |
| Alias `*.100` | LaunchAgent `com.eternal.joplin-hotspot-alias` (опционально + sudoers) |
| Лог rclone | `~/Library/Logs/joplin-webdav/rclone.log` |
| Лог alias | `~/Library/Logs/joplin-webdav/alias.log` |
| Лог Joplin Mac | `~/.config/joplin-desktop/log.txt` |
| Настройки Mac | `~/.config/joplin-desktop/settings.json` → `sync.6.path` |

Скрипты: `docs/apps/joplin/scripts/`.

---

## Шаг 0: диагностика

```bash
./docs/apps/joplin/scripts/joplin-webdav-status.sh
./docs/apps/joplin/scripts/joplin-hotspot-alias.sh status
```

| Что смотреть | OK | Проблема |
|--------------|-----|----------|
| rclone / `:8080` | процесс слушает | `joplin-webdav-serve.sh` или `joplin-webdav-install.sh` |
| `alias: OK` | `*.100` на en0 | `joplin-hotspot-alias.sh ensure` (sudo) |
| rclone.log | `from 10.` или `from 192.` | только `127.0.0.1` — телефон не достучался |
| Mac URL | `127.0.0.1:8080` | настроить WebDAV на Mac |

---

## Правильные URL

### Android раздаёт хотспот, Mac — клиент Wi‑Fi (основной сценарий)

| Устройство | WebDAV URL |
|------------|------------|
| **Mac** | `http://127.0.0.1:8080` |
| **Телефон** | `http://<подсеть>.100:8080` — сейчас часто `http://10.74.21.100:8080` |

Узнать актуальный URL:

```bash
./docs/apps/joplin/scripts/joplin-hotspot-alias.sh status
# или
grep JOPLIN_PHONE_URL ~/.config/joplin-webdav/env
```

**Не использовать на телефоне:**

| URL | Почему |
|-----|--------|
| `http://eternals.local:8080` | Android-хотспот **не резолвит** `.local` клиентов; в rclone.log нет запросов с телефона |
| `http://10.219.227.100:8080` | старая подсеть, если хотспот уже выдал `10.74.x` |
| `http://10.x.x.84:8080` (primary DHCP) | IP меняется при reconnect |

### Общее для Joplin

- Логин: `joplin`
- Пароль: `JOPLIN_WEBDAV_PASS` из env
- **Без** `/` в конце URL
- **Без пробела** в конце
- `http://`, не `https://`
- **Настройки → Синхронизация → Self-hosting → WebDAV** (не «Прокси»)

После смены URL на Mac: **Quit Joplin** → открыть снова → **Синхронизировать**.

---

## Симптом → причина → действие

### 1. «Синк OK, заметок нет на Mac»

Mac Joplin не на WebDAV — в `~/JoplinSync` только данные с телефона.

→ URL `http://127.0.0.1:8080`, проверить конфигурацию, синк.

---

### 2. `ETIMEDOUT` / `connect ETIMEDOUT 10.x.x.x:8080`

**Причина:** на телефоне **устаревший IP** (другая подсеть или нет alias `.100`).

**Признаки:** Joplin `ETIMEDOUT`; rclone — нет свежих `GET`/`PUT` с `10.`.

**Действие:**

```bash
./docs/apps/joplin/scripts/joplin-hotspot-alias.sh ensure   # sudo
./docs/apps/joplin/scripts/joplin-hotspot-alias.sh status   # новый URL
```

→ Обновить URL на телефоне **только если сменилась подсеть** (`10.219` → `10.74`).

---

### 3. `401 Unauthorized`

Пароль в Joplin ≠ env, или rclone не перезапущен.

```bash
grep JOPLIN_WEBDAV_PASS ~/.config/joplin-webdav/env
./docs/apps/joplin/scripts/joplin-webdav-reload.sh
```

---

### 4. `Not a valid URL: …/info.json`

Пробел в конце URL в настройках Joplin → переписать URL.

---

### 5. Порт 8080 не слушает

```bash
./docs/apps/joplin/scripts/joplin-webdav-status.sh
./docs/apps/joplin/scripts/joplin-webdav-serve.sh
```

Лог: `~/Library/Logs/joplin-webdav/launchd.err.log`.

---

### 6. `ECONNREFUSED` / телефон «не достаёт», Mac — да

**Причина:** alias **`*.100` отсутствует** на `en0` (слетел после reconnect).

```bash
ifconfig en0 | grep inet
./docs/apps/joplin/scripts/joplin-hotspot-alias.sh status
curl -s -o /dev/null -w '%{http_code}\n' http://10.74.21.100:8080/   # подставьте *.100 из status
```

→ `joplin-hotspot-alias.sh ensure`  
→ В браузере **на телефоне**: `http://<subnet>.100:8080` — запрос логина  
→ Нет интернета на Mac: [HOTSPOT_NETWORK_EMERGENCY.md](../../HOTSPOT_NETWORK_EMERGENCY.md)

---

### 7. `eternals.local` / `*.local` не работает с телефона

**Ожидаемо.** mDNS на Mac резолвится, Android-хотспот — нет. Использовать **`http://<subnet>.100:8080`**, не `.local`.

---

## Процедура: переподключили хотспот / сменили Wi‑Fi

### 1. Интернет на Mac

Если `curl` / браузер мёртвы:

```bash
bash /Users/eternal/code/local_machine/docs/connectivity/scripts/macos-hotspot-network-recover.sh recover
```

Wi‑Fi должен быть **DHCP**, не Manual ([HOTSPOT_NETWORK_EMERGENCY.md](../../HOTSPOT_NETWORK_EMERGENCY.md)).

### 2. Joplin

```bash
./docs/apps/joplin/scripts/joplin-webdav-status.sh
./docs/apps/joplin/scripts/joplin-hotspot-alias.sh ensure    # если alias MISSING
```

Чеклист:

- [ ] rclone слушает `:8080`
- [ ] `alias: OK` (или `ensure` выполнен)
- [ ] **Mac:** `http://127.0.0.1:8080` — без изменений
- [ ] **Телефон:** URL из `status` — **не менять**, если подсеть та же (`10.74.21.x`)
- [ ] Подсеть **сменилась** → один раз новый `http://<new-subnet>.100:8080`
- [ ] В rclone.log появились `from 10.` после синка на телефоне

### 3. Авто-alias (рекомендуется один раз)

```bash
bash ./docs/apps/joplin/scripts/joplin-android-hotspot-setup.sh install
bash ./docs/apps/joplin/scripts/joplin-hotspot-alias-install-sudo.sh
```

LaunchAgent поднимает `*.100` каждые 60 с после reconnect.

---

## Скрипты

| Скрипт | Когда |
|--------|--------|
| `joplin-webdav-status.sh` | Первая диагностика |
| `joplin-hotspot-alias.sh status\|ensure` | URL телефона, поднять alias |
| `joplin-android-hotspot-setup.sh install` | Полная настройка хотспота |
| `joplin-hotspot-alias-install-sudo.sh` | Alias без пароля (LaunchAgent) |
| `joplin-webdav-install.sh` | Первая установка rclone + launchd |
| `joplin-webdav-reload.sh` | После смены пароля в env |
| `joplin-mdns-setup.sh` | Справочно; **не для URL на телефоне-хотспоте** |

Путь: `docs/apps/joplin/scripts/`.

---

## Логи

**rclone.log** — успех: `PROPFIND`, `GET`, `PUT from <IP>`. Телефон часто виден как IP **шлюза** (`10.74.21.61`), не IP Mac — нормально для Android.

**log.txt Mac:**

```bash
grep -E 'Synchronizer: \[error\]|ETIMEDOUT|ECONNREFUSED|Unauthorized|Not a valid URL' \
  ~/.config/joplin-desktop/log.txt | tail -20
```

---

## Безопасность

- WebDAV только в LAN (`0.0.0.0:8080` пока rclone работает); не пробрасывать в интернет.
- env и пароль — не в git.

---

## Связанные документы

| Документ | Зачем |
|----------|--------|
| [STABLE_SETUP.md](./STABLE_SETUP.md) | Схема alias `*.100`, установка |
| [README.md](./README.md) | Оглавление |
| [docs/apps/joplin/README.md](../../../apps/joplin/README.md) | Установка с нуля |
| [HOTSPOT_NETWORK_EMERGENCY.md](../../HOTSPOT_NETWORK_EMERGENCY.md) | Сеть macOS после reconnect |

---

## История инцидентов

| Дата | Симптом | Корень | Фикс |
|------|---------|--------|------|
| 2026-06-02 | 401 | Пароль env ≠ Joplin | `joplin-webdav-reload.sh` |
| 2026-06-08 | ETIMEDOUT | Старый IP на телефоне | Обновить URL |
| 2026-06-09 | Телефон не достаёт `.100` | Mac без alias | `joplin-hotspot-alias ensure` |
| 2026-06-15 | Нет интернета после reconnect | Manual Wi‑Fi + битые маршруты | `macos-hotspot-network-recover.sh recover`, DHCP |
| 2026-06-19 | `eternals.local` не работает | Android-хотспот не резолвит mDNS клиентов | URL `http://10.74.21.100:8080` + alias |
| 2026-06-19 | Синк OK | alias `.100` + LaunchAgent | [STABLE_SETUP.md](./STABLE_SETUP.md) |

---

*Актуальный URL телефона: `./docs/apps/joplin/scripts/joplin-hotspot-alias.sh status`.*