pacod-demo

pacod-demo пуска идентичността, AI шлюза, платформата за агенти, CMS, базата знания и бенчмарковете на шлюза заедно на една машина, от един конфигурационен файл и с един make. Включва compose файла на всяко хранилище непроменен, дава им по един екземпляр от всеки общ компонент, запознава продуктите един с друг и проверява, че работят като едно цяло; всяка нощ се връща към известно състояние.

Възможности

Екранни снимки

Изпробвайте го

Демото работи на demo.pacod.io, а началната му страница води до всичко останало: всеки продукт с описание, екранна снимка и връзки към администрацията и сайтовете му. Всеки продукт отговаря на собствен поддомейн, всички зад една входна точка:

Адрес	Какво
demo.pacod.io	Началната страница: всеки продукт с връзките си
app.demo.pacod.io	Платформата за агенти (pacod-ap): сайтът ѝ, чатът и администраторската конзола
console.demo.pacod.io	Конзолата на шлюза (pacod-gw): доставчици, модели, ключове, потребление
gw.demo.pacod.io/v1	OpenAI-съвместимото API на шлюза, с ключ за шлюза
studio.demo.pacod.io	Студиото на CMS (pacod-cms)
cms.demo.pacod.io	Demo Journal, сайт на CMS; Demo Notes е на minimal., Starward на space.
kb.demo.pacod.io	Базата знания (pacod-kb)
bench.demo.pacod.io	Бенчмарковете на шлюза (pacod-benchmark): набори, пускания, сравнения
id.demo.pacod.io/admin	Администриране на идентичността (pacod-id)
grafana.demo.pacod.io	Таблата на всички продукти
mail.demo.pacod.io	Всяко писмо, което стекът изпраща
prometheus.demo.pacod.io	Метриките, за ad-hoc заявки

Едно влизане покрива всички продукти: който влезе в един, е влязъл във всички. Самостоятелна регистрация няма: акаунтите идват от администратора и с покана, а без акаунт сайтовете и публичните страници на продуктите са отворени за всички. Grafana, Prometheus и прегледът на пощата вместо това искат имейла и паролата на администратора. Всяка промяна се отменя при следващото нощно нулиране.

Защо съществува

Всеки проект на PACOD работи самостоятелно, със собствени копия на онова, от което има нужда: база данни, входна точка, влизане, шлюз. Така е най-добре да се изпробва поотделно. Но не така са замислени да се използват заедно, и така не се вижда какво дават заедно.

pacod-demo е обратното. Слага шестте продукта на една машина като една платформа, с по един екземпляр от всеки общ компонент, и показва онова, което се появява само когато работят заедно: едно влизане, което всеки продукт признава, един шлюз, през който минава всяко обръщение към модел и който ги остойностява всичките, бенчмарк, който измерва същия този шлюз, и един набор от табла за целия стек. Той е и образецът за това как продуктите се сглобяват: конвенцията за мрежата и имената, на която се опира, docs/NETWORK.md, се спазва от всяко хранилище.

Как е сглобен

Стекът е един compose проект, pacod-demo: 42 услуги, две от които се изпълняват веднъж при старта и спират (43 с незадължителния ingestion).

От	Какво работи в демото	Имена
pacod-id	Доставчикът на идентичност, с един realm за всички продукти	pacod-id
pacod-gw	Ядрото, аналитиката, конзолата, тестерът, ClickHouse, Valkey на кеша на отговорите, mock доставчикът и агентът и mock-ът за натоварване на тестовете му	pacod-gw, gw-*
pacod-ap	API, admin API, MCP сървър, workers, frontend, Redis и pgbouncer, общата услуга за embeddings и експортерите на наблюдението му	ap-*, pacod-embeddings, експортерите
pacod-cms	Сайтовете, студиото, MongoDB и Gotenberg	cms-*
pacod-kb	Pipeline и потребителският интерфейс	kb-*
pacod-benchmark	API и потребителският интерфейс	bench-*
pacod-demo	Caddy, PostgreSQL, Qdrant, Mailpit, Prometheus, Alertmanager, Grafana и колекторът на OpenTelemetry	pacod-*

• Две мрежи, уникални имена. Всеки контейнер влиза във външната Docker мрежа pacod-net под име, уникално за всички хранилища: общите компоненти се казват pacod-*, всичко останало носи префикса на собственика си. Слушателите, до които трябва да стигат само сървъри, управляващото API на шлюза, вътрешният слушател на pacod-id и API на бенчмарка, са във втора мрежа, pacod-admin-net, която е вътрешна (без път навън). Всеки се свързва към псевдоним, който съществува само там, и в нея влизат само тези, които ги извикват.
• Собствените compose файлове на хранилищата. Всяко хранилище разделя compose настройката си на app файл, със собствените си услуги, и standalone файл, със собствени копия на общите компоненти за самостоятелна работа. compose.yml включва шестте app файла непроменени, заедно с файловете за разработка и за тестове с натоварване на шлюза. Малък overlay за всяко хранилище само премахва публикуваните портове, задава тайните и публичните адреси на демото и насочва настройките към файловете на демото.
• По един от всеки общ компонент. platform.yml не пише нито един от нулата: всеки разширява (extends) дефиницията, която някое хранилище вече има, и взима приноса на продуктите от директориите им platform/: блоковете за Caddy, скриптовете за бази данни, задачите, правилата и таблата за Prometheus. PostgreSQL има база данни и роля-собственик за всеки продукт.
• Хранилищата за данни на продуктите остават при тях: ClickHouse и Valkey на шлюза, MongoDB (по една база данни на сайт) и Gotenberg на CMS, Redis и pgbouncer на платформата за агенти.
• Генерираното състояние е в .state/, което git игнорира: тайните, създадени веднъж и никога не сменяни, удостоверенията, които прави bootstrap, и променливите на всеки продукт, генерирани от demo.env.

Какво прави make up

1. Предварителна проверка. Docker и Compose 2.24 или по-нов, памет и диск, шестте съседни хранилища във варианта с обща мрежа, никой друг pacod стек да не държи общите имена, паролата на администратора, сертификатът и портовете. Блокиращ проблем го спира тук.
2. Мрежи и тайни. Създава pacod-net и вътрешната pacod-admin-net, после генерира всяка тайна веднъж в .state/secrets.env. Ако тайните ги няма, а томовете с данни са налице, отказва, вместо да създаде нови тайни, с които данните не могат да работят.
3. Генериране. От demo.env стават собствените променливи на всеки продукт в .state/env/<product>.env.
4. Старт. Compose стартира проекта и чака, докато всяка услуга стане здрава. Първият старт изгражда всеки образ от изходния код и изтегля модела за embeddings.
5. Bootstrap. Управлява собствените скриптове на продуктите, bootstrap на pacod-ap за шлюза и идентичността и provisioner на pacod-cms, за да създаде ключовете за шлюза и служебните токени, с които продуктите се достигат един друг. Създава и токена на pacod-benchmark за управляващото API на шлюза (администратор на платформата: бенчмаркът създава и премахва собствена организация за всяко пускане) и дава на администратора всяка роля, която му липсва. Услугите, които четат тези удостоверения, се пресъздават.
6. Начални данни. Таблиците на платформата за агенти, референтните факти на стартовия агент и потребителите му за разработка.
7. Базово състояние. При нов стек изчаква CMS да запише трите си демо сайта и тогава запазва данните като базово състояние.
8. Планировчик. Стартира контейнера на нощното нулиране, после отпечатва адресите и паролата на администратора.

Нощното нулиране

Всеки ден в DEMO_RESET_TIME (по подразбиране 05:00) в DEMO_RESET_TIMEZONE (по подразбиране UTC) демото отменя всяка промяна: акаунти, агенти, статии, документи, ключове и настройки. Началната страница го обявява в лента под заглавието си, с часа в часовата зона на посетителя и колко остава до следващото.

• Базовото състояние е данните на стека в един момент: каквото е направило първото make up или каквото make baseline запази по-късно. То съдържа всеки том с данни (PostgreSQL, MongoDB, Qdrant, ClickHouse, Redis, файловете на базата знания и на приложението, Grafana, Alertmanager), файловете на CMS и удостоверенията на bootstrap, компресирани в Docker тома pacod-demo-baseline.
• Не съдържа: моделите, метриките на Prometheus, собствените данни на входната точка и кеша на отговорите на шлюза, който живее в паметта: всяко нулиране го изпразва.
• Бенчмарковете също се връщат: пусканията и графиците на pacod-benchmark, шлюзовете, добавени в интерфейса му, и отчетите, публикувани в конзолата на шлюза. Отчет, който искате да запазите, се изтегля от страницата на пускането му; конзолата го приема обратно чрез качване.
• Как. Всички услуги без входната точка спират, така че началната страница остава достъпна, докато продуктите отговарят с 502 няколко минути. Базовото състояние се копира обратно, стекът стартира и bootstrap се изпълнява отново, като прилага и добавен междувременно ключ на доставчик. make reset прави същото, веднага.
• Планировчикът е контейнерът pacod-demo-reset, извън compose проекта, защото нулирането спира проекта. Пропуска нощта, когато стекът не работи или машината е била заспала. Празно DEMO_RESET_TIME го изключва.

Конфигурация

Два файла. demo.env е конфигурацията: домейните, на стека и на сайтовете, портовете, сертификатът, имейлът на първия администратор, часът на нулирането, моделите на всеки продукт, бекендът за embeddings, незадължителният компонент и логовете. Git го игнорира; първото make го копира от шаблона в хранилището, demo.env.example, и спира, за да го редактирате. demo.local.env пази тайните на машината, паролата на администратора и ключовете на доставчиците на LLM; git игнорира и него, а каквото задава, има предимство.

# demo.local.env
DEMO_ADMIN_PASSWORD=a-long-passphrase
ANTHROPIC_API_KEY=sk-...

Доставчици на LLM. Без зададен ключ всяко обръщение към модел отива към mock доставчика на шлюза: демото работи офлайн и make verify е детерминистичен, но отговорите в чата са предварително зададени. Добавете ключ (моделите по подразбиране на платформата за агенти са на Anthropic) и изпълнете make bootstrap, и шлюзът се настройва с реалния доставчик. AP_PRIMARY_MODEL, AP_CLASSIFIER_MODEL, CMS_AI_MODEL и KB_LLM_MODEL избират моделите, които продуктите искат от шлюза.

Бекендът за embeddings се фиксира при първото make up, защото съхранените вектори зависят от него. По подразбиране, auto, пуска BGE-M3, когато Docker има около 8 GB памет, а под това — лек заместител; смяната по-късно изисква make clean.

Незадължителният компонент ingestion пуска приемането на документи на платформата за агенти и зарежда базата знания на стартовия агент; без него агентът отговаря само от референтните си факти. Образът му е около 10 GB и може да използва 7 GiB памет, затова иска 16 GiB за Docker.

Логове. Всеки продукт логва в един общ формат, по едно събитие на ред със същите ключове навсякъде (docs/LOGGING.md). DEMO_LOG_LEVEL и DEMO_LOG_FORMAT (text или json) ги задават всички, както и дневника на заявките на входната точка.

Демо сайтовете на CMS се записват само при първия старт на студиото. make cms-seed попълва сайт без статии, а make cms-space създава Starward в стек, стартиран преди той да съществува. Starward и началната страница могат да получат и етикет на Google Analytics и проверка за Search Console в demo.env; оставени празни, както е по подразбиране, на страницата няма нищо от Google.

Сигурност

• Един публикуван порт. Само входната точка, pacod-caddy, публикува портове; всяка друга услуга е достъпна само в Docker мрежите. Слушателите за сървъри са във вътрешната pacod-admin-net, свързани към псевдоними, до които pacod-net не стига.
• Тайни. Всяка тайна се генерира веднъж на машината и никога не се записва в хранилището. Паролата на администратора трябва да има 12 или повече знака (pacod-id отказва по-къса); ако е празна, се генерира парола от 24 знака.
• Домейнът на сайтовете. Сайт на CMS изпълнява скрипта на собственика си, който на регистрируемия домейн на студиото би могъл да задава бисквитки, получавани от студиото и от влизането. Затова сайтовете получават собствен домейн (DEMO_SITE_DOMAIN); на домейна на студиото студиото отказва да стартира. DEMO_SITE_DOMAIN_SHARED=true ги слага под домейна на демото, за демо, чиито сайтове са до един доверени, и само през HTTPS. demo.pacod.io прави точно това: всичките му сайтове са негови.
• Когато е публикуван извън машината (DEMO_BIND не е loopback адрес), демото затваря онова, което е безопасно само на лаптоп: прегледът на пощата, Prometheus и Grafana искат имейла и паролата на администратора, /grafana на конзолата на шлюза отговаря 403, началната страница не назовава администратора, а токените за разработка на платформата за агенти са изключени. Собствената администрация на продуктите е зад тяхното влизане, както винаги.
• Сертификатите се предоставят, не се издават автоматично: един сертификат за домейна, поддомейните му и домейна на сайтовете.

На домейн или на лаптоп

Със зададени DEMO_TLS_CERT и DEMO_TLS_KEY стекът отговаря по HTTPS, а обикновеният HTTP само пренасочва към него. В DNS домейнът, wildcard записът му и wildcard записът на сайтовете трябва да сочат към сървъра; преди това make hosts отпечатва редове за /etc/hosts, за да го изпробвате.

Шаблонът в хранилището е този на публичния сървър. За демо само на една машина demo.env има нужда от пет настройки:

DEMO_DOMAIN=localhost
DEMO_TLS_CERT=
DEMO_TLS_KEY=
DEMO_HTTP_PORT=8800
DEMO_BIND=127.0.0.1

Тогава всичко е по обикновен HTTP на http://<name>.localhost:8800, което браузърите разрешават без DNS (Safari може и да не успее: ползвайте друг браузър или make hosts).

Какво му трябва

• Docker с Compose 2.24 или по-нов и make. Всичко останало, от тайните до проверките, работи в контейнери.
• Шестте продуктови хранилища, изтеглени до това.
• Около 8 GB памет за Docker. Целият стек с истинския модел за embeddings използваше около 5 GiB при измерването, преди pacod-benchmark да се присъедини; бенчмаркът с агента и mock-а за натоварване на шлюза добавя под 100 MiB в покой. С лекия заместител — около 4 GiB.
• Около 30 GiB диск за образите. Първото make up изгражда всеки образ от изходния код, три Rust workspace-а, един Maven build, няколко Python образа и три SvelteKit приложения, и отнема от 30 до 60 минути. Следващите стартирания отнемат около две минути.

make down спира стека и запазва данните; make clean премахва всичко, което демото е създало. След изтегляне на нови версии make build изгражда образите наново (make up изгражда само липсващите), а make reset, последвано от make baseline, прави мигрираните данни новото базово състояние.

Какво е тествано и докъде стига

make verify проверява работещия стек от край до край и завършва с 1, когато нещо се провали:

Част	Какво проверява
Docker	По един екземпляр от всеки общ компонент, само входната точка публикува порт, никоя услуга не е спряла или нездрава, pacod-admin-net е вътрешна и в нея са само тези, които извикват слушателите
Входна точка и здраве	Адресът и health endpoint-ът на всеки продукт, всяка цел на Prometheus е достъпна, правилата и таблата на шлюза и на приложението са заредени
Единно влизане	Администраторът влиза веднъж и е пуснат в приложението, конзолата на шлюза, студиото, базата знания и бенчмарка без ново влизане, и има всяка роля, която трябва
Шлюз	Ключовете на платформата за агенти, на CMS и на базата знания изброяват модели и завършват чат; повторено обръщение получава отговор от кеша на отговорите
Продукти	Поточен ход на чата през шлюза (само на лаптоп); документ, приет, намерен и изтрит в базата знания; Demo Journal се показва, а Starward — върху набора magazine
Бенчмарк	Токенът му е администратор на платформата в шлюза, а шлюзът приема отчетите му

Докъде стига:

• Агентът за натоварване на бенчмарка работи на същата машина като шлюза: числата му показват как се държи шлюзът, а не капацитета му.
• Числата за паметта са измерени, преди pacod-benchmark да влезе в стека.
• Нулирането прави продуктите недостъпни за няколко минути, а планировчикът пропуска нощ, в която машината е спала.
• Без ключ на доставчик всеки отговор е на mock-а; с ключ обръщенията са истински и струват пари.
• Стек, стартиран преди Starward или с по-ранната му версия, изисква ръчна стъпка, за да го получи; README я описва, заедно с пълния списък с настройки и таблица за отстраняване на проблеми.

Бърз старт

Изтеглете седемте хранилища едно до друго

mkdir pacod && cd pacod
for r in pacod-demo pacod-id pacod-gw pacod-ap pacod-cms pacod-kb pacod-benchmark; do git clone https://github.com/pacod22/$r.git; done

Настройте го само за тази машина

cd pacod-demo
cp demo.env.example demo.env
printf '%s\n' DEMO_DOMAIN=localhost DEMO_TLS_CERT= DEMO_TLS_KEY= DEMO_HTTP_PORT=8800 DEMO_BIND=127.0.0.1 >> demo.env

Изградете, стартирайте и проверете стека

make up
make verify
open http://localhost:8800

Работи с

• pacod-id: Единственият доставчик на идентичност в стека, с един realm, през който влиза всеки продукт; bootstrap дава на администратора ролята на всеки продукт.
• pacod-gw: Единственият шлюз в стека, стартиран с включен кеш на отговорите; bootstrap дава на всеки продукт собствен ключ за шлюза.
• pacod-ap: Пуска стартовия агент, малко измислено бюро за помощ, със сайта, чата и администраторската конзола.
• pacod-cms: Пуска студиото, с AI помощта му при писане, и три демо сайта, Demo Journal, Demo Notes и Starward.
• pacod-kb: Пуска базата знания върху общите Qdrant, PostgreSQL и услуга за embeddings.
• pacod-benchmark: Измерва собствения шлюз на стека с агента за натоварване и mock доставчика на шлюза; отчетите му се показват в конзолата на шлюза.