82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
# Bell
|
|
|
|
Bell is YoVision's independently deployable alert intake and response product. It owns its users, roles, sessions, database, audit facts and release artifacts. Sense and Brain are not required for Bell to build or run.
|
|
|
|
## Frozen baseline
|
|
|
|
- Go `1.26.5`
|
|
- Node.js `22.22.1`
|
|
- pnpm `9.15.1`
|
|
- go-admin commit `f06540883b41d03782bb6b2c4150f298f328c6b6`
|
|
- go-admin-ui commit `67d393d713877572fab0b897296a4c1d525fc81d`
|
|
|
|
Exact upstream sources and retained MIT notices are in `LICENSES/`.
|
|
|
|
## Configuration
|
|
|
|
Copy variable names from `.env.example` into the process environment. Replace every placeholder at deployment time. Bell intentionally has no built-in database password, session secret or administrator password.
|
|
|
|
`BELL_SESSION_SECRET` is mandatory, must be at least 32 characters, and must be generated independently from Sense. In production Bell marks its `bell_session` cookie as Secure, HttpOnly and SameSite=Strict.
|
|
|
|
The PostgreSQL role used by `BELL_DATABASE_URL` must be dedicated to Bell. Do not reuse a Sense role or database.
|
|
|
|
## Backend
|
|
|
|
```powershell
|
|
Set-Location Bell/server
|
|
go test ./...
|
|
go run . migrate
|
|
go run . serve
|
|
```
|
|
|
|
Create the first administrator only through a one-time process environment value; do not place the password in shell history, source files or command arguments:
|
|
|
|
```powershell
|
|
$env:BELL_BOOTSTRAP_PASSWORD = Read-Host -AsSecureString | ConvertFrom-SecureString -AsPlainText
|
|
go run . create-admin --username bell-admin --display-name "Bell 管理员"
|
|
Remove-Item Env:BELL_BOOTSTRAP_PASSWORD
|
|
```
|
|
|
|
Passwords require at least 12 characters with upper-case, lower-case and numeric characters. Bell ships no user or default password. Administrator, operator and viewer roles are seeded with least-privilege permissions; only an administrator can read user and authentication-audit pages.
|
|
|
|
Health endpoints:
|
|
|
|
```powershell
|
|
Invoke-RestMethod http://127.0.0.1:8082/healthz
|
|
Invoke-RestMethod http://127.0.0.1:8082/readyz
|
|
```
|
|
|
|
Migrations are embedded and applied transactionally. The `migrate` command is idempotent. To roll back this initial skeleton, stop Bell and drop only the dedicated Bell test database; migrations are forward-only and never touch another product database.
|
|
|
|
## Web
|
|
|
|
```powershell
|
|
Set-Location Bell/web
|
|
pnpm install --frozen-lockfile
|
|
pnpm lint
|
|
pnpm build:prod
|
|
pnpm dev
|
|
```
|
|
|
|
The web client listens on port 8083 in development and proxies `/api` to Bell only. The visible shell contains only Bell's product navigation; go-admin demonstration routes are neither registered nor served by the backend.
|
|
|
|
### Development-only synthetic events
|
|
|
|
When `BELL_ENV=development` or `test`, administrators can open “合成事件测试” or call the `/api/v1/synthetic/*` endpoints. Fixtures live under `server/testdata/events/`, contain only invented anonymous data, and call the same Event/Receipt service as every future producer adapter. Reusing a source event ID verifies idempotency; using the same ID with a different fixture verifies conflict handling.
|
|
|
|
In `BELL_ENV=production` those routes are not registered and return `404`; hiding the menu is not the security boundary.
|
|
|
|
### Rules and alerts
|
|
|
|
Administrators configure and enable rules from “规则配置”. Each accepted Event is evaluated in the same database transaction that creates its Event/Receipt. A matching Event creates or joins an open Alert correlated by rule and location; one Event may match several rules and one Alert may collect several related Events. Every evaluation records its rule version and explanation, while every match also stores the actual rule snapshot. Unmatched Events remain visible as Events and are never labelled as notified or handled.
|
|
|
|
Alert handling is two-step: the first authorized operator to acknowledge becomes the handler, then that handler (or an administrator) records a required site outcome before closing. PostgreSQL conditional updates select one concurrent acknowledgement winner. Later operators receive the actual handler instead of overwriting it. Successful lifecycle facts are append-only; failed, duplicate and denied attempts are also written to the security audit without tokens or passwords.
|
|
|
|
## Independent smoke check
|
|
|
|
Run PostgreSQL with an empty Bell-only database, set `BELL_DATABASE_URL`, start the backend and then the web client. Keep Sense and Brain stopped. Verify `/healthz`, `/readyz`, the workbench shell, and a direct request to an unregistered framework demo route returns `404`.
|
|
|
|
## Logs and secrets
|
|
|
|
Application logs go to standard output. Never log database URLs, passwords, session tokens, event evidence credentials, customer data or production payloads.
|