Server Deploy

Server Deploy — самостоятельно развёртываемый стек Memoh для постоянной работы с несколькими пользователями или арендаторами. Используйте его, когда Memoh должен работать на сервере, виртуальной машине или NAS, или когда Bot должны продолжать обслуживать внешние каналы, пока ваш компьютер не в сети.

На этой странице описано серверное развёртывание через Docker Compose. О нативном локальном клиенте см. Установка Desktop.

Стек Compose по умолчанию включает PostgreSQL, базу pgvector для эмбеддингов памяти, одноразовую задачу миграции, основной сервер с явно заданным бэкендом рабочих пространств и ИИ-агентом в том же процессе, воркер каналов и веб-клиент. PostgreSQL — единственная поддерживаемая база данных.

Официальный стек Compose использует бэкенд рабочих пространств containerd. Образ сервера запускает встроенный containerd и монтирует файлы рантайма, нужные рабочим пространствам Bot. О бэкендах Docker Engine и Apple см. Бэкенды рабочих пространств.

Архитектура сервисов

Стек Docker Compose состоит из нескольких сервисов. Часть из них запускается всегда, остальные — необязательные и включаются через --profile:

Сервис	Профиль	Описание
server	(основной)	Основной сервер Memoh с настроенным бэкендом контейнерного рантайма и ИИ-агентом в том же процессе
channel	(основной)	Воркер каналов (memoh-channel), который владеет подключениями к платформам и вебхуками; общается с сервером по внутреннему RPC
web	(основной)	Веб-клиент (Vue 3)
postgres	(основной)	База данных PostgreSQL (основное хранилище данных)
pgvector	(основной)	PostgreSQL с pgvector для необязательных эмбеддингов памяти; см. Встроенная память
migrate	(основной, одноразовый)	Выполняет memoh-server migrate up до старта сервера
webhook-tunnel	webhook-tunnel	Необязательный быстрый туннель cloudflared, открывающий слушатель вебхуков воркера каналов в интернет
connect-it	connectors	Совместно размещённый сервис Connect-It, на который опираются коннекторы Bot (см. ниже)

Коннекторы Connect-It

Контейнер connect-it запускает Connect-It — сервис, стоящий за коннекторами Bot: он связывает сторонние сервисы вроде GitHub и Notion с Bot через OAuth или ключи API. Он использует общий с Memoh экземпляр PostgreSQL, храня данные изолированно в отдельной схеме connect_it, и сам управляет своими миграциями.

Скрипт установки полностью берёт Connect-It на себя:

• Чистая установка включает его по умолчанию (MEMOH_CONNECT_IT_MODE=embedded, профиль Compose connectors); коннекторы работают сразу, без ручного создания токена в консоли администратора Connect-It.
• Обновление оставляет его выключенным, если он не был включён раньше; чтобы включить, перезапустите скрипт установки с MEMOH_CONNECT_IT_MODE=embedded.
• Все учётные данные — пароль администратора, ключ AES, cookie secret и межсерверный API-токен — генерируются один раз, записываются в .env и переиспользуются при обновлениях. Последующее переключение режимов не теряет существующие подключения.

После установки консоль администратора Connect-It доступна по адресу http://localhost:8421 (пользователь admin; сгенерированный пароль печатается в конце установки и хранится в .env).

Два момента, за которыми стоит следить:

• OAuth-колбэки идут через публичный адрес Connect-It, по умолчанию http://localhost:8421. Если к Memoh обращаются с других машин, задайте в MEMOH_CONNECT_IT_PUBLIC_BASE_URL адрес, доступный этим машинам (и провайдерам OAuth).
• Зеркала для материкового Китая: образ Connect-It лежит на ghcr.io, который зеркало memoh.cn не покрывает. Если ghcr.io недоступен, задайте MEMOH_CONNECT_IT_MODE=disabled, чтобы пропустить его.

Предварительные требования

• Docker
• Docker Compose v2
• Git

Server Deploy в одну команду (рекомендуется)

Запустите официальный скрипт установки (нужны Docker и Docker Compose):

curl -fsSL https://memoh.sh | sh

Запускайте установщик от обычного пользователя. Не оборачивайте весь скрипт в sudo; скрипт сам применит sudo docker внутри, и только если Docker этого требует. Если вам намеренно нужно запустить весь установщик от root, явно задайте MEMOH_ALLOW_ROOT_INSTALL=true.

Скрипт:

1. Проверит наличие Docker и Docker Compose
2. Определит, что это: первая установка, обновление или переустановка
3. Запросит настройки (рабочее пространство, каталог данных, учётные данные администратора, секрет JWT, пароль Postgres, а также покажет уведомление о бэкенде рабочих пространств)
4. При обновлении автоматически переиспользует существующий config.toml, чтобы учётные данные базы совпадали с сохранённым томом PostgreSQL
5. Предложит режим чистой переустановки, который перед новым запуском удаляет контейнеры, тома и сеть Memoh в Docker
6. Получит тег последнего релиза с GitHub и клонирует репозиторий
7. При необходимости сгенерирует config.toml из Docker-шаблона с вашими настройками
8. Откажется обновлять устаревшие установки на SQLite (поддерживается только PostgreSQL; выберите чистую переустановку)
9. Закрепит версии Docker-образов Memoh на релизе (например, v0.13.0 использует тег образа 0.13.0)
10. При чистой установке подготовит совместно размещённый Connect-It: один раз сгенерирует его учётные данные, сохранит их в .env и добавит профиль connectors (см. Коннекторы Connect-It)
11. Запустит docker-compose.yml (основные сервисы), добавив профили connectors и webhook-tunnel, если они включены
12. При сбое запуска автоматически выведет свежие логи базы данных, миграций и сервера

Тихая установка (все значения по умолчанию, без вопросов):

curl -fsSL https://memoh.sh | sh -s -- -y

Значения по умолчанию в тихом режиме:

• Рабочее пространство: ~/memoh
• Каталог данных: ~/memoh/data
• Администратор: admin / admin123
• Секрет JWT: генерируется автоматически
• База данных: PostgreSQL (с сайдкаром pgvector)
• Пароль Postgres: memoh123
• Туннель вебхуков: отключён, если не задано MEMOH_WEBHOOK_TUNNEL_MODE=external

Если в тихом режиме скрипт обнаруживает существующую установку Memoh, он по умолчанию выполняет обновление и переиспользует прежний config.toml. Если состояние Docker есть, а пригодный для переиспользования config.toml найти не удалось, скрипт завершается и просит явно выбрать переустановку.

Принудительная чистая переустановка (перед новым запуском удаляет данные Memoh в Docker):

curl -fsSL https://memoh.sh | MEMOH_INSTALL_MODE=reinstall sh

Режим установки можно передать и аргументом:

curl -fsSL https://memoh.sh | sh -s -- --install-mode reinstall

Установка конкретной версии:

curl -fsSL https://memoh.sh | sh -s -- --version v0.13.0

Или через переменную окружения:

curl -fsSL https://memoh.sh | MEMOH_VERSION=v0.13.0 sh

Зеркало для материкового Китая (если образы скачиваются медленно):

curl -fsSL https://memoh.sh | USE_CN_MIRROR=true sh

Переменные окружения можно сочетать, например curl -fsSL https://memoh.sh | MEMOH_VERSION=v0.13.0 USE_CN_MIRROR=true sh

Публикация вебхуков каналов через быстрый туннель Cloudflare (для платформ, которым нужен публичный URL обратного вызова):

curl -fsSL https://memoh.sh | MEMOH_WEBHOOK_TUNNEL_MODE=external sh

Параметры скрипта установки

Скрипт установки принимает следующие флаги после sh -s --:

Параметр	Описание
-y, --yes	Тихий запуск со значениями по умолчанию. Скрипт также сам переключается в тихий режим, когда TTY недоступен.
--version <tag>, --version=<tag>	Установить конкретный Git-тег, например v0.13.0.
--install-mode <mode>, --install-mode=<mode>	Выбрать auto, fresh, upgrade или reinstall.
--database-driver <driver>, --database-driver=<driver>	Принимается для совместимости; поддерживается только значение postgres.
--container-backend <backend>, --workspace-backend <backend>	Выбрать значение бэкенда рабочих пространств, записываемое в конфигурацию. Установка Docker Compose в одну команду поддерживает только containerd; для docker или apple используйте ручное развёртывание.

Ручная установка

git clone https://github.com/felinics/Memoh.git
cd Memoh
cp conf/app.docker.toml config.toml

Отредактируйте config.toml — как минимум измените:

• admin.password — пароль администратора
• auth.jwt_secret — сгенерируйте командой openssl rand -base64 32
• postgres.password — пароль базы данных (задайте такое же значение в переменной окружения POSTGRES_PASSWORD)

Затем запустите основные сервисы:

POSTGRES_PASSWORD=your-db-password docker compose up -d

При необходимости добавьте --profile connectors для совместно размещённого Connect-It и --profile webhook-tunnel для сайдкара вебхуков Cloudflare.

На macOS, а также если ваш пользователь состоит в группе docker, sudo не требуется.

Важно: docker-compose.yml по умолчанию монтирует ./config.toml. Создайте этот файл до запуска — без него старт завершится ошибкой.

Чтобы включить коннекторы при ручном развёртывании, сгенерируйте учётные данные Connect-It самостоятельно и добавьте профиль connectors:

MEMOH_CONNECT_IT_BASE_URL="http://connect-it:8421" \
MEMOH_CONNECT_IT_API_TOKEN="cit_$(openssl rand -hex 32)" \
MEMOH_CONNECT_IT_SECRET_KEY="1:$(openssl rand -hex 32)" \
MEMOH_CONNECT_IT_COOKIE_SECRET="$(openssl rand -base64 32)" \
MEMOH_CONNECT_IT_ADMIN_PASSWORD="choose-a-password" \
POSTGRES_PASSWORD=your-db-password \
docker compose --profile connectors up -d

Сохраняйте те же значения между перезапусками (например, в файле .env): API-токен — это то, что Memoh предъявляет Connect-It, а секретный ключ шифрует сохранённые учётные данные. Скрипт установки делает всё это автоматически.

Зеркало для материкового Китая

Пользователям в материковом Китае, у которых нет прямого доступа к Docker Hub, нужно раскомментировать строку registry в config.toml:

[container]
registry = "memoh.cn"
image_pull_policy = "if_not_present" # if_not_present, always или never

И подключить compose-оверлей с китайским зеркалом:

docker compose -f docker-compose.yml -f docker/docker-compose.cn.yml up -d

Скрипт установки делает это автоматически, когда задано USE_CN_MIRROR=true.

Точки доступа

После запуска:

Сервис	URL
Веб-клиент	http://localhost:8082
API	http://localhost:8080
Консоль администратора Connect-It (с профилем connectors)	http://localhost:8421

Вход по умолчанию: admin / admin123 (поменяйте это в config.toml). В консоль администратора Connect-It входят как admin с паролем, сгенерированным установщиком (он печатается в конце установки и хранится в .env).

Первый запуск может занять 1–2 минуты, пока скачиваются образы и инициализируются сервисы.

Справочник по конфигурации

Файл config.toml управляет всем поведением сервера. Краткая сводка доступных секций:

Секция	Описание
[log]	Уровень и формат логирования (info, debug; text, json)
[server]	Адрес прослушивания HTTP (по умолчанию :8080)
[admin]	Учётные данные администратора (имя пользователя, пароль, email)
[auth]	Секрет JWT и срок действия токенов
timezone	Часовой пояс сервера (по умолчанию UTC)
[database]	Драйвер базы данных; поддерживается только postgres
[container]	Выбор бэкенда рабочих пространств, а также общий образ рабочих пространств, политика загрузки, путь к данным, путь к рантайму и настройки CNI
[containerd]	Путь к сокету containerd и namespace
[docker]	Переопределение хоста Docker Engine; пустое значение — окружение Docker или сокет по умолчанию
[apple]	Переопределения сокета socktainer и бинарника для бэкенда Apple
[postgres]	Подключение к PostgreSQL (host, port, user, password, database, sslmode)
[pgvector]	Необязательная база pgvector для эмбеддингов памяти (enabled, host, port, user, password, database, sslmode)
[internal_rpc]	RPC-адреса сервера и воркера каналов и общий секрет для раздельного развёртывания
[webhook_tunnel]	Режим туннеля вебхуков (disabled или external) и public_base_url
[registry]	Каталог с определениями провайдеров
[connect_it]	Эндпоинт Connect-It для коннекторов (base_url, api_token); если оба пустые, функция отключена. В окружении Compose их переопределяют MEMOH_CONNECT_IT_BASE_URL / MEMOH_CONNECT_IT_API_TOKEN.
[web]	Хост и порт веб-фронтенда
[agent]	Лимиты усечения вывода инструментов: tool_output_max_bytes (по умолчанию 65536), tool_output_max_lines (по умолчанию 2000), system_files_max_bytes (по умолчанию 32768). У слишком большого вывода сохраняются начало и конец, а не обрезается всё подряд.
[session_runtime]	Бэкенд состояния сессий для развёртывания в несколько экземпляров; см. Развёртывание в несколько экземпляров

Развёртывание в несколько экземпляров

Развёртыванию в один экземпляр всё это не нужно: состояние сессий по умолчанию живёт в памяти процесса, а долговременный журнал — в базе данных.

Чтобы запустить за балансировщиком нагрузки больше одного экземпляра сервера Memoh, состояние сессий для ходов агента должно переехать в общий бэкенд. Настройте блок [session_runtime]:

[session_runtime]
backend = "redis"   # "memory" (по умолчанию, только для одного экземпляра) или "redis"
cluster = true       # объявляет режим нескольких экземпляров; требует backend = "redis"
# state_ttl = "24h"
# owner_lease_ttl = "30s"

[session_runtime.redis]
url = "redis://redis:6379/0"
# key_prefix = "memoh:session_runtime:"

Примечания:

• redis означает протокол Redis; Valkey тоже подходит. В комплектном стеке Docker Compose сервиса Redis/Valkey нет — добавьте свой.
• Сочетание cluster = true с бэкендом memory намеренно приводит к ошибке при запуске.
• С бэкендом Redis сервер проверяет доступность Redis при старте и отказывается запускаться, если тот недоступен.

Основные команды

В Linux добавляйте sudo перед командами, если ваш пользователь не состоит в группе docker.

docker compose up -d           # Запуск
docker compose down            # Остановка
docker compose down -v         # Остановка и удаление данных Memoh в Docker
docker compose logs -f         # Просмотр логов
docker compose ps              # Статус
docker compose pull && docker compose up -d  # Обновление до свежих образов

Переменные окружения

Переменная	По умолчанию	Описание
POSTGRES_PASSWORD	memoh123	Пароль PostgreSQL (должен совпадать с postgres.password в config.toml)
MEMOH_CONFIG	./config.toml	Путь к файлу конфигурации
MEMOH_DATA_DIR	~/memoh/data	Значение каталога данных, которое установщик записывает в .env; пока зарезервировано под будущую поддержку bind-монтирования.
MEMOH_VERSION	(последний релиз)	Git-тег для установки (например, v0.13.0). Также закрепляет версии Docker-образов Memoh на теге без начальной v (например, 0.13.0).
MEMOH_INSTALL_MODE	auto	Режим установки: auto, fresh, upgrade или reinstall
MEMOH_DATABASE_DRIVER	postgres	Принимается для совместимости; поддерживается только значение postgres
MEMOH_CONTAINER_BACKEND	containerd	Бэкенд рабочих пространств. Установка Docker Compose в одну команду поддерживает containerd; для docker или apple используйте ручное развёртывание.
MEMOH_ALLOW_ROOT_INSTALL	false	Разрешить запуск самой оболочки установщика от root. Лучше не задавать эту переменную и запускать установщик от обычного пользователя.
MEMOH_WEBHOOK_TUNNEL_MODE	disabled	external добавляет профиль webhook-tunnel (сайдкар Cloudflare cloudflared), чтобы вебхуки каналов получили публичный URL.
USE_CN_MIRROR	false	Установите true, чтобы использовать зеркала образов в материковом Китае
MEMOH_CONNECT_IT_MODE	embedded при чистой установке; при обновлениях не меняется	embedded запускает совместно размещённый Connect-It (профиль connectors); disabled отключает коннекторы.
MEMOH_CONNECT_IT_PUBLIC_BASE_URL	http://localhost:8421	Публичный URL для OAuth-колбэков коннекторов и консоли администратора. Задайте его, если Memoh используется с других машин.
MEMOH_CONNECT_IT_PORT	8421	Порт хоста для контейнера Connect-It.
MEMOH_CONNECT_IT_IMAGE	(закреплено за релизом)	Переопределение образа Connect-It.

Остальные значения MEMOH_CONNECT_IT_* (пароль администратора, секретный ключ, cookie secret, API-токен) — учётные данные, которые установщик генерирует один раз и сохраняет в .env; обычно задавать их вручную незачем.