thakares
83218ba602
- Refresh administrator guide - Update architecture documentation - Document Registry Validator - Document Registry Repair Framework - Update backup and restore guide - Refresh CLI documentation - Update Docker deployment example - Bump version to v0.5.3
889 lines
9.1 KiB
Markdown
889 lines
9.1 KiB
Markdown
# BZOD Administrator Guide
|
|
|
|
Version: v0.5.3
|
|
|
|
---
|
|
|
|
# Introduction
|
|
|
|
This guide is intended for BZOD administrators responsible for operating, maintaining, and managing a BZOD instance.
|
|
|
|
It covers:
|
|
|
|
* Administrator authentication
|
|
* User management
|
|
* Quotas
|
|
* Sessions
|
|
* Moderation
|
|
* Slug ownership
|
|
* Analytics
|
|
* Audit logs
|
|
* Backup and recovery
|
|
* Health monitoring
|
|
* Operational best practices
|
|
|
|
---
|
|
|
|
# Administrator Role
|
|
|
|
Administrators have full platform control.
|
|
|
|
Administrative capabilities include:
|
|
|
|
* Create users
|
|
* Modify users
|
|
* Disable users
|
|
* Delete users
|
|
* Reset passwords
|
|
* Manage quotas
|
|
* Review analytics
|
|
* Moderate content
|
|
* Transfer slug ownership
|
|
* Manage backups
|
|
* Review audit logs
|
|
* Monitor system health
|
|
|
|
Administrators cannot bypass audit logging.
|
|
|
|
All administrative actions are recorded.
|
|
|
|
---
|
|
|
|
# Login
|
|
|
|
Administrative login is available at:
|
|
|
|
```text
|
|
/login
|
|
```
|
|
|
|
Successful login redirects to:
|
|
|
|
```text
|
|
/admin
|
|
```
|
|
|
|
Authentication uses:
|
|
|
|
```text
|
|
users.db
|
|
```
|
|
|
|
Sessions are stored in:
|
|
|
|
```text
|
|
users.db.sessions
|
|
```
|
|
|
|
Cookie name:
|
|
|
|
```text
|
|
bzod_session
|
|
```
|
|
|
|
---
|
|
|
|
# Administrative Dashboard
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin
|
|
```
|
|
|
|
The dashboard provides a high-level overview of platform activity.
|
|
|
|
Metrics include:
|
|
|
|
* Total Users
|
|
* Active Users
|
|
* Total URLs
|
|
* Total Landing Pages
|
|
* Active Sessions
|
|
* API Tokens
|
|
* Storage Usage
|
|
* Moderation Events
|
|
* Recent Audit Events
|
|
|
|
Quick actions include:
|
|
|
|
* Create User
|
|
* View Sessions
|
|
* View Audit Logs
|
|
* Create Backup
|
|
* Review Health Status
|
|
|
|
---
|
|
|
|
# User Management
|
|
|
|
## Users List
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users
|
|
```
|
|
|
|
Displays:
|
|
|
|
* User ID
|
|
* Username
|
|
* Status
|
|
* Account Type
|
|
* Creation Date
|
|
|
|
Available actions:
|
|
|
|
* View
|
|
* Edit
|
|
* Disable
|
|
* Enable
|
|
* Reset Password
|
|
* Delete
|
|
|
|
---
|
|
|
|
## Create User
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/new
|
|
```
|
|
|
|
Fields:
|
|
|
|
* Username
|
|
* Password
|
|
* Account Type
|
|
* Quota Limits
|
|
|
|
Supported account types:
|
|
|
|
```text
|
|
admin
|
|
standard
|
|
```
|
|
|
|
Reserved usernames cannot be used.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
admin
|
|
legacy_admin
|
|
system
|
|
root
|
|
administrator
|
|
```
|
|
|
|
---
|
|
|
|
## User Detail Page
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/{id}
|
|
```
|
|
|
|
Displays:
|
|
|
|
### Profile
|
|
|
|
* User ID
|
|
* Username
|
|
* Status
|
|
* Account Type
|
|
* Created Date
|
|
|
|
### Usage Statistics
|
|
|
|
* URL Count
|
|
* Landing Page Count
|
|
* Visit Count
|
|
* Storage Usage
|
|
* API Token Count
|
|
* Active Sessions
|
|
|
|
### Quotas
|
|
|
|
* Maximum URLs
|
|
* Maximum Pages
|
|
* Maximum Storage
|
|
* Maximum Tokens
|
|
|
|
### Sessions
|
|
|
|
List of active sessions.
|
|
|
|
### API Tokens
|
|
|
|
List of active tokens.
|
|
|
|
---
|
|
|
|
## Edit User
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/{id}/edit
|
|
```
|
|
|
|
Administrators may:
|
|
|
|
* Change status
|
|
* Change account type
|
|
* Modify quotas
|
|
|
|
---
|
|
|
|
## Reset Password
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/{id}/password
|
|
```
|
|
|
|
Creates a new password hash and invalidates existing sessions.
|
|
|
|
Audit event generated:
|
|
|
|
```text
|
|
password_reset
|
|
```
|
|
|
|
---
|
|
|
|
## Disable User
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/{id}/disable
|
|
```
|
|
|
|
Effects:
|
|
|
|
* User login disabled
|
|
* Existing sessions revoked
|
|
* API access denied
|
|
|
|
Audit event generated:
|
|
|
|
```text
|
|
user_disabled
|
|
```
|
|
|
|
---
|
|
|
|
## Enable User
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/{id}/enable
|
|
```
|
|
|
|
Restores account access.
|
|
|
|
Audit event generated:
|
|
|
|
```text
|
|
user_enabled
|
|
```
|
|
|
|
---
|
|
|
|
## Delete User
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/users/{id}/delete
|
|
```
|
|
|
|
Deletion performs:
|
|
|
|
1. Session revocation
|
|
2. API token removal
|
|
3. Content removal
|
|
4. Analytics removal
|
|
5. Slug release
|
|
6. User database deletion
|
|
|
|
Audit event generated:
|
|
|
|
```text
|
|
user_deleted
|
|
```
|
|
|
|
---
|
|
|
|
# Session Management
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/sessions
|
|
```
|
|
|
|
Displays all active platform sessions.
|
|
|
|
Information displayed:
|
|
|
|
* User ID
|
|
* Username
|
|
* Session Identifier
|
|
* Created Time
|
|
* Expiry Time
|
|
* IP Address
|
|
* User Agent
|
|
|
|
---
|
|
|
|
## Revoke Session
|
|
|
|
Individual sessions can be revoked.
|
|
|
|
Effects:
|
|
|
|
* Session removed immediately
|
|
* User forced to reauthenticate
|
|
|
|
---
|
|
|
|
## Revoke All Sessions
|
|
|
|
Administrators may invalidate all active sessions.
|
|
|
|
Useful after:
|
|
|
|
* Password compromise
|
|
* Security incidents
|
|
* Large configuration changes
|
|
|
|
---
|
|
|
|
# Quota Management
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/quotas
|
|
```
|
|
|
|
Quotas limit user resource consumption.
|
|
|
|
Available limits:
|
|
|
|
```text
|
|
max_urls
|
|
max_pages
|
|
max_storage_mb
|
|
max_api_tokens
|
|
```
|
|
|
|
---
|
|
|
|
## Quota Reconciliation
|
|
|
|
Administrators can execute:
|
|
|
|
```text
|
|
quota_reconcile
|
|
```
|
|
|
|
Purpose:
|
|
|
|
* Detect counter drift
|
|
* Recount resources
|
|
* Repair quota usage
|
|
|
|
Common causes:
|
|
|
|
* Manual database modifications
|
|
* Failed migrations
|
|
* Interrupted operations
|
|
|
|
---
|
|
|
|
# Moderation
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/moderation
|
|
```
|
|
|
|
Moderation allows administrators to manage abuse and policy violations.
|
|
|
|
---
|
|
|
|
## Flag Content
|
|
|
|
Marks content for review.
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
content_flagged
|
|
```
|
|
|
|
---
|
|
|
|
## Disable Content
|
|
|
|
Disabled content returns:
|
|
|
|
```http
|
|
410 Gone
|
|
```
|
|
|
|
Affected endpoints:
|
|
|
|
```text
|
|
/{slug}
|
|
/p/{slug}
|
|
/api/qr/{slug}.png
|
|
/api/qr/{slug}.svg
|
|
```
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
content_disabled
|
|
```
|
|
|
|
---
|
|
|
|
## Enable Content
|
|
|
|
Restores functionality.
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
content_enabled
|
|
```
|
|
|
|
---
|
|
|
|
## Delete Content
|
|
|
|
Permanently removes content.
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
content_deleted
|
|
```
|
|
|
|
---
|
|
|
|
# Slug Management
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/slugs
|
|
```
|
|
|
|
Displays platform-wide slug ownership.
|
|
|
|
Information includes:
|
|
|
|
* Slug
|
|
* Owner
|
|
* Type
|
|
* Status
|
|
* Creation Date
|
|
|
|
---
|
|
|
|
## Slug Types
|
|
|
|
Supported types:
|
|
|
|
```text
|
|
url
|
|
page
|
|
```
|
|
|
|
---
|
|
|
|
## Transfer Ownership
|
|
|
|
Administrators may transfer ownership.
|
|
|
|
Workflow:
|
|
|
|
1. Validate recipient quota.
|
|
2. Copy content.
|
|
3. Update ownership.
|
|
4. Update global slug registry.
|
|
5. Write audit record.
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
slug_transfer
|
|
```
|
|
|
|
Analytics are preserved.
|
|
|
|
---
|
|
|
|
# Analytics
|
|
|
|
Administrators can access analytics for any managed resource.
|
|
|
|
---
|
|
|
|
## URL Analytics
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/analytics/url/{id}
|
|
```
|
|
|
|
Displays:
|
|
|
|
* Total Visits
|
|
* Unique Visitors
|
|
* Referrers
|
|
* Browsers
|
|
* Countries
|
|
* Visit Timeline
|
|
|
|
---
|
|
|
|
## Page Analytics
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/analytics/page/{id}
|
|
```
|
|
|
|
Displays identical metrics for landing pages.
|
|
|
|
---
|
|
|
|
## User Analytics
|
|
|
|
Administrators can review user-level analytics.
|
|
|
|
Route:
|
|
|
|
```text
|
|
/analytics
|
|
```
|
|
|
|
Includes:
|
|
|
|
* Top Links
|
|
* Top Pages
|
|
* Referrers
|
|
* Browsers
|
|
* Countries
|
|
* Recent Visits
|
|
|
|
---
|
|
|
|
# Audit Logs
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/audit
|
|
```
|
|
|
|
All administrative actions are recorded.
|
|
|
|
Searchable event types include:
|
|
|
|
```text
|
|
login
|
|
logout
|
|
failed_login
|
|
user_created
|
|
user_deleted
|
|
user_disabled
|
|
user_enabled
|
|
password_reset
|
|
quota_updated
|
|
slug_transfer
|
|
content_flagged
|
|
content_disabled
|
|
backup_created
|
|
restore_executed
|
|
```
|
|
|
|
Audit logs should be reviewed regularly.
|
|
|
|
---
|
|
|
|
# Backup Management
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/backups
|
|
```
|
|
|
|
Provides web-based backup operations.
|
|
|
|
---
|
|
|
|
## Create Backup
|
|
|
|
Creates a platform snapshot.
|
|
|
|
Includes:
|
|
|
|
```text
|
|
users.db
|
|
system.db
|
|
tenant databases
|
|
```
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
backup_created
|
|
```
|
|
|
|
---
|
|
|
|
## Download Backup
|
|
|
|
Allows local storage of backup archives.
|
|
|
|
Recommended frequency:
|
|
|
|
```text
|
|
Daily
|
|
```
|
|
|
|
---
|
|
|
|
## Restore Backup
|
|
|
|
Restores a selected backup archive.
|
|
|
|
Audit event:
|
|
|
|
```text
|
|
restore_executed
|
|
```
|
|
|
|
Always test restores before production use.
|
|
|
|
---
|
|
|
|
## Delete Backup
|
|
|
|
Removes backup archives from storage.
|
|
|
|
---
|
|
|
|
# Health Dashboard
|
|
|
|
Route:
|
|
|
|
```text
|
|
/admin/health
|
|
```
|
|
|
|
Provides operational diagnostics.
|
|
|
|
Displays:
|
|
|
|
* Database Status
|
|
* WAL Status
|
|
* Storage Utilization
|
|
* Backup Status
|
|
* Health Check Results
|
|
* Quota Reconciliation Results
|
|
|
|
---
|
|
|
|
## Database Health
|
|
|
|
Checks:
|
|
|
|
```text
|
|
users.db
|
|
system.db
|
|
content.db
|
|
analytics.db
|
|
```
|
|
|
|
Reports:
|
|
|
|
```text
|
|
healthy
|
|
warning
|
|
error
|
|
```
|
|
|
|
---
|
|
|
|
## Storage Monitoring
|
|
|
|
Shows:
|
|
|
|
* Total Storage
|
|
* Free Storage
|
|
* Database Sizes
|
|
* Backup Sizes
|
|
|
|
---
|
|
|
|
# Security Administration
|
|
|
|
## Password Policies
|
|
|
|
Recommendations:
|
|
|
|
* Minimum 12 characters
|
|
* Unique passwords
|
|
* Password manager usage
|
|
|
|
---
|
|
|
|
## Session Management
|
|
|
|
Recommended actions:
|
|
|
|
* Revoke old sessions
|
|
* Review active sessions
|
|
* Remove inactive users
|
|
|
|
---
|
|
|
|
## CSRF Protection
|
|
|
|
All administrative forms require valid CSRF tokens.
|
|
|
|
Invalid requests return:
|
|
|
|
```http
|
|
403 Forbidden
|
|
```
|
|
|
|
---
|
|
|
|
## Audit Reviews
|
|
|
|
Recommended review schedule:
|
|
|
|
| Event Type | Frequency |
|
|
| ----------------- | --------- |
|
|
| Failed Logins | Daily |
|
|
| User Creation | Weekly |
|
|
| Slug Transfers | Weekly |
|
|
| Backup Events | Daily |
|
|
| Moderation Events | Weekly |
|
|
|
|
---
|
|
|
|
# Disaster Recovery
|
|
|
|
Recommended workflow:
|
|
|
|
1. Stop BZOD.
|
|
2. Create backup copy.
|
|
3. Restore archive.
|
|
4. Verify databases.
|
|
5. Run integrity checks.
|
|
6. Restart service.
|
|
|
|
---
|
|
|
|
# Operational Best Practices
|
|
|
|
Recommended:
|
|
|
|
* Enable HTTPS
|
|
* Run daily backups
|
|
* Monitor disk usage
|
|
* Review audit logs
|
|
* Keep binaries updated
|
|
* Test restore procedures regularly
|
|
|
|
Avoid:
|
|
|
|
* Manual database modifications
|
|
* Direct deletion of tenant databases
|
|
* Disabling audit logging
|
|
|
|
---
|
|
|
|
# Troubleshooting
|
|
|
|
## User Cannot Login
|
|
|
|
Check:
|
|
|
|
* User status
|
|
* Session validity
|
|
* Password reset history
|
|
|
|
---
|
|
|
|
## Slug Already Exists
|
|
|
|
Check:
|
|
|
|
```text
|
|
/admin/slugs
|
|
```
|
|
|
|
for ownership conflicts.
|
|
|
|
---
|
|
|
|
## Analytics Missing
|
|
|
|
Verify:
|
|
|
|
* Analytics worker running
|
|
* Analytics database present
|
|
* Event queue processing
|
|
|
|
---
|
|
|
|
## Backup Failure
|
|
|
|
Check:
|
|
|
|
* Free disk space
|
|
* File permissions
|
|
* Backup destination path
|
|
|
|
---
|
|
|
|
# Summary
|
|
|
|
The BZOD administration system provides:
|
|
|
|
* Centralized user management
|
|
* Quotas and session controls
|
|
* Moderation and slug ownership management
|
|
* Analytics visibility
|
|
* Audit logging
|
|
* Backup and restore capabilities
|
|
* Health monitoring
|
|
|
|
while maintaining strong tenant isolation and a SQLite-native operational model.
|
|
|
|
---
|
|
|
|
End of Document.
|