Эррата — это вкладка с опечатками, которую вкладывают в книгу. Оба исправления 3.6.3 нашлись одинаково: открываешь страницу, которая работала, и получаешь 404. Первое — срез пути, из-за которого имя файла теряло первую букву. Второе — конфиг, который при неудачном чтении заменялся умолчаниями. Основной разбор платформы — в статье MD Viewer: просмотрщик Markdown без браузерного движка; здесь про MD.Scribe 3.6.3, механику обеих ошибок и что проверено на живом прогоне.

TL;DR: две ошибки, один симптом
- Имена без первой буквы.
index.mdотображался какndex.md, и каждая ссылка из браузера вела в 404. - Причина — симлинк. Обход шёл по разрешённому пути, а срез считался от неразрешённого; префиксы разной длины.
- Конфиг не перезаписывается. Нечитаемый файл настроек теперь даёт работу на умолчаниях и строку в логе, а не потерю 1 166 байт.
- Проверка. Прогон на раскладке релиза: имена полные,
?file=docs/upgrade-from-v2.mdотвечает 200. - Архив: 4 272 892 байта, 1 023 записи, манифест 3.6.3.
Что нового
| Область | Изменение |
|---|---|
| Пути | относительный путь считается от разрешённого корня |
| Вне корня | путь логируется и пропускается, а не обрезается |
| Тесты | три теста на раскладку с симлинком |
| Конфиг | различаются «распарсено», «пусто» и «есть, но не читается» |
| Запись конфига | при нечитаемом файле запрещена, событие в журнале |
| Тесты конфига | два, на Windows пропускаются |
Ключевые изменения
Срез пути и потерянная буква
flowchart TB ROOT["корень обзора: разрешённый realpath"] --> WALK["обход файлов"] WALK --> FULL["полный путь файла"] FULL --> CUT["срез префикса"] CUT --> REL["относительный путь в ссылке"] REL --> VIEW["просмотр ?file=..."]
Механика такая. Проверка пути возвращает каталог, уже развёрнутый через realpath(). Обход идёт по этой базе. А относительный путь строился как substr($full, strlen($root)), где $root — неразрешённый корень обзора.
Пока content — обычный каталог, оба префикса совпадают, и всё работает. Но в раскладке релиза content это симлинк: <release>/content -> mdscribe-data/content. Длины префиксов расходятся, срез попадает внутрь последнего сегмента, и каждый файл в подкаталоге теряет первую букву.
На боевом сайте это выглядело так: index.md показывался как ndex.md, а autoyap-roles-security-2026-11-13.md — как utoyap-roles-security-2026-11-13.md. При этом сам просмотрщик был исправен: прямой запрос с правильным путём отдавал 200. То есть сломана была не отрисовка, а генерация ссылок.
Теперь путь считается от того же разрешённого корня, с которого начался обход, а путь вне корня логируется и пропускается вместо обрезки. Три теста строят раскладку с симлинком; со старой арифметикой все три падают.
Конфиг, который нельзя прочитать
flowchart TD
L["загрузка настроек"] --> R{"файл читается?"}
R -- да --> USE["работа с настройками"]
R -- нет --> SAFE["умолчания, запись запрещена"]
SAFE --> LOG["строка в журнале ошибок"]Вторая ошибка опаснее первой, потому что тихая. Config::load() считал «файл есть» равнозначным «файл читается», продолжал работу с пустыми значениями и вызывал appendMissingKeys() — а тот перезаписывал файл.
В проде это выглядело так: конфиг, записанный из CLI от root с правами root:root 0640, не читался пулом веб-сервера. Следующий запрос заменил 1 166 байт настроек умолчаниями — вместе с именем сайта и домашним документом, и без единой строки в логе.
Теперь чтение различает три состояния: ключи распарсены; файл пуст или отсутствует (законный первый запуск); файл есть, но не читается. В третьем случае приложение работает на умолчаниях, писать конфиг запрещено, а в журнал ошибок попадает запись.
Установка и обновление
unzip MD.Scribe-3.6.3.zip -d /srv/releases/3.6.3
chmod -R u+w /srv/releases/3.6.3/storage
ln -sfn /srv/releases/3.6.3 /srv/docs # docroot: /srv/docs/public
| Шаг | Что сделать |
|---|---|
| 1 | сохранить каталог данных (mdscribe-data или ваш) |
| 2 | распаковать архив в новый каталог релиза |
| 3 | убедиться, что content — симлинк на данные, а не копия |
| 4 | переключить симлинк docroot |
| 5 | сбросить opcache |
| 6 | открыть список файлов и проверить имена |
Проверка после обновления
flowchart LR SYM["content — симлинк"] --> MIS["префиксы разной длины"] MIS --> TRUNC["имя без первой буквы"] TRUNC --> E404["ссылка ведёт в 404"] E404 --> FIX["срез от того же корня"] FIX --> OK["полные имена и 200"]
| Проверка | Ожидаемо |
|---|---|
| Список файлов | полные имена, без потери первой буквы |
| Файл в подкаталоге | ссылка вида ?file=docs/upgrade-from-v2.md отвечает 200 |
| Имя сайта | прежнее, не «MD.Scribe» по умолчанию |
| Домашний документ | прежний, а не index.md из умолчаний |
| Журнал ошибок | нет записей о нечитаемом конфиге |
| Права на конфиг | владелец — пользователь пула, не root |
Замеры и цифры
Проверено 15.11.2026, двумя проверками.
| Что | Значение |
|---|---|
Архив MD.Scribe-3.6.3.zip |
4 272 892 байта, SHA-256 80da2cc0…7dc1852 |
| Записей в архиве | 1 023, отсортированы |
| Режимы файлов | все 420 (0o644) |
| Манифест | MD.Scribe 3.6.3, php_min 8.5.0, 988 файлов |
Прогон: раскладка релиза с симлинком content |
собрана, сервер PHP 8.5.4 |
| Главная страница | 200 |
| Ссылки в разметке | file=index.md, file=getting-started.md, file=docs/api.md — полные, без обрезки |
?file=index.md |
200 |
?file=getting-started.md |
200 |
?file=docs/markdown-reference.md |
200 |
?file=docs/upgrade-from-v2.md |
200 |
Прогон специально воспроизводил ту самую раскладку: каталог content вынесен в данные и подключён симлинком. Именно в ней старая арифметика ломалась. Результат — имена в разметке полные, а файл из подкаталога открывается по прямой ссылке; раньше такой запрос давал 404, потому что имя приходило без первой буквы и без папки.
Заодно проверка показала, что в демо-контенте намеренно есть ссылка на отсутствующий файл (definitely-missing.md) — это иллюстрация страницы 404, а не дефект.
Совместимость
| Параметр | 3.6.2 | 3.6.3 |
|---|---|---|
| Минимум PHP | 8.5.0 | 8.5.0 |
| Файлов в манифесте | 988 | 988 |
| Архив | 4 267 955 байт | 4 272 892 байта |
| Записей в архиве | 1 022 | 1 023 |
Минимум PHP не менялся. Условия, при которых ошибка проявлялась, — симлинк на каталоге контента и права конфига, отличающиеся от пользователя пула.
| Кто обновляется | Что учесть |
|---|---|
| с 3.6.0–3.6.2 | проверьте имя сайта и домашний документ: они могли сброситься на умолчания |
| с 3.5.0 | то же плюс проверка симлинка content |
| с 3.1.0 | нужен PHP 8.5 |
Подводные камни
- Проверяйте владельца конфига. Файл, записанный от root, пул не прочитает; до 3.6.3 это приводило к перезаписи умолчаниями.
- Запись конфига — от пользователя пула. Из CLI это значит запуск через
su/sudo -u, а не от root. - Симлинк
content— часть раскладки. Если заменить его копией, ошибка не воспроизведётся, но и обновления будут терять контент. - Имена без первой буквы — признак среза пути. Если увидели
ndex.md, дело не в шаблоне. - 404 при работающем просмотрщике. Проверяйте прямой запрос с полным путём: если он даёт 200, ломается генерация ссылок.
- Пустой конфиг — законный случай. Первый запуск отличается от нечитаемого файла; не путайте при диагностике.
- Логи теперь говорят. После 3.6.3 событие «конфиг не читается» попадает в журнал ошибок — ищите там.
- Кэш браузера. После переключения релиза старые ссылки могут остаться в кэше.
- opcache. Без сброса увидите старую версию кода и решите, что исправление не помогло.
- Демо-ссылка на отсутствующий файл. Не считайте её регрессией.
FAQ
Почему имена теряли первую букву?
Обход шёл по разрешённому пути, а префикс для среза брался от неразрешённого. При симлинке длины различались, и срез съедал первый символ.
Почему просмотрщик при этом работал?
Потому что ломалась генерация ссылок, а не разрешение пути: прямой запрос с корректным путём отдавал 200.
Что было с конфигом?
Нечитаемый файл считался пустым, и приложение перезаписывало его умолчаниями, теряя настройки без записи в лог.
Как проверить, что меня это коснулось?
Сравните имя сайта и домашний документ с ожидаемыми: если там значения по умолчанию, настройки были сброшены.
Как писать конфиг, чтобы не повторить?
От имени пользователя пула: файл с владельцем root пул не прочитает.
Нужен ли PHP 8.5?
Да, минимум не менялся с 3.5.0.
Итог
MD.Scribe 3.6.3 — релиз про две ошибки, которые не выглядели ошибками: имена файлов без первой буквы и конфиг, который «сам сбрасывался». Обе нашлись с одной стороны — со стороны пользователя, упёршегося в 404 и в пропавшие настройки. Исправления точечные: путь считается от того же разрешённого корня, а нечитаемый конфиг больше не перезаписывается. Прогон на раскладке с симлинком подтверждает: имена полные, файл из подкаталога открывается, манифест показывает 3.6.3 с 988 файлами.
Цитата: Самая дорогая ошибка — та, что выглядит как особенность: имя без буквы и настройки «сами сбросились».
Связанные материалы
- MD Viewer: просмотрщик Markdown без браузерного движка — основной разбор платформы.
- MD.Scribe 3.6.2: воспроизводимый архив и настройки — предыдущий релиз и история с
.md.ini. - MD.Scribe 3.5.0: Mermaid 12 и починенный ремонт — диаграммы и авторемонт схем.
- sr-search-replace: замена по дереву с журналом — про откат и предпросмотр в инструментах.
- Релиз v3.6.3 — заметки и архив.
LLM Summary
- Тема: MD.Scribe 3.6.3 «Errata» — исправление среза пути в списке файлов и защита конфига от перезаписи умолчаниями.
- Дефект 1:
scan()строил относительный путь какsubstr($full, strlen($root)), где$full— путь от базы, развёрнутойrealpath(), а$root— неразрешённый корень обзора; при симлинкеcontent -> mdscribe-data/contentпрефиксы разной длины и первый символ имени терялся. В проде:index.md→ndex.md,autoyap-roles-security-2026-11-13.md→utoyap-roles-security-2026-11-13.md, все ссылки из браузера давали 404 при исправном просмотрщике. - Исправление 1: путь считается от того же разрешённого корня, путь вне корня логируется и пропускается; три теста на раскладку с симлинком, со старой арифметикой падают все три.
- Дефект 2:
Config::load()считал «файл есть» равным «файл читается» и вызывалappendMissingKeys(), перезаписывая настройки умолчаниями; в проде конфигroot:root 0640не читался пулом, и 1 166 байт настроек (имя сайта, домашний документ) были потеряны без записи в лог. - Исправление 2: различаются распарсенные ключи, пустой/отсутствующий файл и существующий нечитаемый; в последнем случае работа на умолчаниях, запись запрещена, событие в журнале; два теста (на Windows пропускаются).
- Проверено 15.11.2026: архив — 4 272 892 байта, SHA-256
80da2cc0532471efb5110be241077330501ba0c0f9811748b294264ab7dc1852, 1 023 записи, отсортированы, режимы 420, манифест 3.6.3 / 988 файлов /php_min8.5.0. - Прогон на раскладке релиза (PHP 8.5.4,
content— симлинк на данные): главная 200, ссылки в разметке полные;?file=index.md,?file=getting-started.md,?file=docs/markdown-reference.md,?file=docs/upgrade-from-v2.md— все 200. - Грабли: конфиг писать от пользователя пула; симлинк
contentне заменять копией; сбрасывать opcache; демо-ссылкаdefinitely-missing.md— намеренная. - Не проверялось: воспроизведение исходного дефекта на коде 3.6.2, работа под нагрузкой, поведение при обновлении DSM-подобных раскладок с несколькими симлинками.
- Ссылки: https://github.com/paulmann/MD.Scribe, https://sysadministrator.ru/md-viewer/
Промт для агента (установка и настройка)
Готовый промт: скопируйте блок целиком. Источник шагов — AGENTS.md и README.md репозитория, сверено с прогоном на раскладке релиза 15.11.2026.
Задача: обновить MD.Scribe до 3.6.3 и убедиться, что список файлов отдаёт полные имена, а настройки не сброшены.
Материалы:
- репозиторий: https://github.com/paulmann/MD.Scribe
- AGENTS.md: https://github.com/paulmann/MD.Scribe/blob/main/AGENTS.md
- README: https://github.com/paulmann/MD.Scribe/blob/main/README.md
- релиз: https://github.com/paulmann/MD.Scribe/releases/tag/v3.6.3
Шаг 1. Сверить SHA-256 архива с указанным в релизе.
Шаг 2. Проверить PHP 8.5 и расширения mbstring, dom, libxml, json, zip.
Шаг 3. Сохранить каталог данных и конфиг .md.ini.
Шаг 4. Распаковать архив в новый каталог релиза, content оставить симлинком на данные.
Шаг 5. Проверить владельца .md.ini: он должен быть пользователем пула, а не root.
Шаг 6. Переключить симлинк docroot и сбросить opcache.
Шаг 7. Открыть список файлов: имена должны быть полными, без потери первой буквы.
Шаг 8. Открыть файл из подкаталога по прямой ссылке ?file=docs/<имя>.md — ожидается 200.
Шаг 9. Сверить имя сайта и домашний документ с ожидаемыми значениями.
Шаг 10. Проверить журнал ошибок: не должно быть записей о нечитаемом конфиге.
Шаг 11. Записать конфиг из CLI только от имени пользователя пула: su -s /bin/sh <pool-user> -c "php ..."
Запрещено:
- писать конфиг от root: пул его не прочитает;
- заменять симлинк content копией каталога;
- проверять после обновления с прогретым opcache;
- считать ссылку на отсутствующий файл регрессией: в демо-контенте она намеренная;
- откатываться на 3.6.2 «если что»: там теряется конфиг при нечитаемом файле;
- игнорировать записи о нечитаемом конфиге в журнале.
Что считать успехом: имена в списке полные, файл из подкаталога открывается по прямой ссылке, настройки на месте, в журнале ошибок нет записей о конфиге, манифест показывает 3.6.3.