web-starter

# Web Starter [](https://github.com/mason2048/web-starter/actions/workflows/ci.yml) [](LICENSE)  `web-starter` is a general-purpose scaffolding for internal Web management systems. It adopts a modular monolithic architecture, providing a Vue management end, REST API, and MCP Server within the same business and security boundary. It is not a finished system bound to a specific industry or business process, but rather an engineering baseline that can be replicated, tailored, and continued to develop: the management end has common system capabilities, REST and MCP reuse the same business services, permission judgments, transactions, and audit trails, and deployment configurations can smoothly transition from local development to internal network environments. ## Project Status The current code version is `2.0.0`. The default branch is used for continuous integration and community collaboration; formal versions are still marked with Git Tag, immutable image digest, and corresponding acceptance evidence. Build passing does not represent deployment, migration, authentication, or end-to-end process passing in your environment. ## Management End Overview  The above diagram shows the capability overview. The management end is organized around users, roles, menu and button permissions, system configurations, audit logs, and example Project CRUD, which can serve as a unified entry point for new business modules. ## Core Capabilities  - **Unified Security Foundation**: Web Session, OAuth access token, PAT, and service account token ultimately map to the same caller identity. - **Shared Business Boundary**: REST API and MCP Tool call the same business Service, sharing transactions, RBAC, and audit rules. - **Replicable Example Module**: Project module covers the complete chain of list, details, add, modify, delete, permissions, migration, and audit. - **面向实际部署**: Provides Docker Compose, Nginx, health check, environment variable configuration, and release acceptance instructions. ## Boundaries - Oriented to internal network management systems, not providing public self-registration, packages, billing, or SaaS multi-tenancy. - Web API and MCP share business Service, database transactions, real-time RBAC, and audit models. - Only provides MCP Server, not connecting or proxying third-party MCP Server. - Does not provide arbitrary SQL, Shell, file system, or dynamic code execution capabilities. - The first version maintains a monolithic deployment, not introducing microservices, service discovery, and distributed transactions. ## Technical Baseline | Layer | Baseline | |---|---| | Frontend | Vue 3.5, TypeScript 5.9, Vite 8, Element Plus 2.14 | | Backend | Java 21, Spring Boot 4.1, Spring Security 7.1 | | Data Access | MyBatis-Plus 3.5, MySQL 8.4, Flyway | | Session | Spring Session, Redis 7.4 | | MCP | MCP Java SDK 2.0, Streamable HTTP | | Deployment | Docker Compose, Nginx | ## Modules ```text web-starter ├── web-starter-core # API, exceptions, Caller, and permission abstraction ├── web-starter-system # Users, roles, menus, configurations, RBAC, and audit ├── web-starter-security # Session, OAuth, PAT, service account token ├── web-starter-project # Replicable complete example CRUD ├── web-starter-mcp # MCP Transport, Resources, Tools, Prompts ├── web-starter-admin # Spring Boot startup, Flyway, and runtime assembly ├── web-starter-web # Vue management end ├── deploy # Nginx configuration └── docs # Architecture, security, deployment, and module replication instructions ``` Dependency direction is maintained as: `admin -> mcp/security/project/system -> core`. MCP Tool can only call business Service, not directly calling Mapper.  The architecture diagram shows the logical call relationship: Web management end and external Agent enter from different entrances, converging into a unified Caller at the adaptation and security layer, and then accessing MySQL, Redis, and audit capabilities through shared business Service. ## Quick Start Requires Docker Desktop or Docker Engine + Compose V2. ```bash cp .env.example .env ``` Replace placeholder values in `.env`. The first empty database startup requires setting a high-strength Bootstrap administrator password; the project does not contain a default password. ```bash chmod 600 .env ./bin/web-starter doctor ./bin/web-starter up ``` `up` waits for MySQL, Redis, application, and Nginx to reach readiness status. Daily shutdown uses `./bin/web-starter down`, defaulting to retain data volume; deleting data volume must be explicitly selected and completed with a second confirmation. Complete parameters and security boundaries see [Offline Generation and Development Tools](docs/tooling.md). The default management end address is `http://localhost:8088`. After successful login, remove the Bootstrap password environment variable and rebuild the application container. Actuator's non-health endpoints do not use Web administrator Session. `info`, `metrics`, `prometheus` require independent `WEB_STARTER_MANAGEMENT_USERNAME` / `WEB_STARTER_MANAGEMENT_PASSWORD`, which refuse to start in production if missing; Nginx does not expose these paths publicly. Specific collection and secret handling requirements see [Deployment and O&M](docs/deployment.md#运维指标认证), formal V2 metrics and trace acceptance see [Observability Runtime Evidence](docs/observability-runtime-evidence.md). Local multi-process development, executable `compose.public-mcp.yaml` dual entrances, independent build-free `compose.production.yaml`, TLS certificate mounting, backup recovery, and digest rollback see [Deployment Instructions](docs/deployment.md). SBOM, actual digest scanning, and vulnerability exception rules see [Supply Chain and Release Image](docs/supply-chain.md). Public network entrance must use HTTPS and cannot directly expose marked `private` default management entrances. ## Development Verification Unified evidence collection entrance is: ```bash ./bin/web-starter verify ``` It records the status of backend, frontend, strategy, container, browser, OAuth, and MCP, respectively; if a layer fails, it continues to collect subsequent evidence. Lack of real operating environment or acceptance implementation will explicitly record `ENV_REQUIRED`/`NOT_COVERED` and return non-zero, not using build success to replace full-stack passing. The following commands can still be used for single-layer troubleshooting: ```bash ./mvnw verify cd web-starter-web pnpm install --frozen-lockfile pnpm lint pnpm typecheck pnpm test pnpm build cd .. python3 scripts/repository_policy.py secrets ``` The root directory's Maven Enforcer requires JDK 21 or higher compatible build JDK and always produces bytecode with `release 21`. Deployment image uniformly uses Java 21 Runtime. Local usage of secret and engineering isolation gate, external forbidden word injection, and exit code convention see [Repository Policy Gate](docs/repository-policy.md). ## Security Model | Caller | Authentication Method | Entrance Suggestion | |---|---|---| | Web Management End | Username/password + Redis Session + CSRF | Internal network management domain name | | External User Agent | Authorization Code + PKCE | HTTPS public MCP domain name | | External Automation Agent | Client Credentials | HTTPS public MCP domain name | | Internal Fixed Agent | PAT or service account token | Controlled private entrance | Each credential ultimately maps to a unified `CurrentCaller`. The final authorization result of token calls is the intersection of "real-time RBAC" and "token Scope"; disabling users/service accounts, revoking tokens, or reclaiming role permissions immediately affects subsequent calls. Long-term tokens only save HMAC-SHA-256 hash and short prompts with Pepper version; plaintext appears only once in creation response; old Pepper verification succeeds and can be transactionally migrated. OAuth Client Secret supports active/retiring overlapping rotation with expiration time. External entrances are marked as `public` by Nginx, and applications refuse PAT and service account long-term tokens. Detailed threat boundaries see [Security Model](docs/security.md).  Each MCP call goes through entrance verification, token authentication, unified Caller resolution, and final authorization of "real-time RBAC and credential Scope intersection," and then enters the business transaction and records Trace ID, call result, and time-consuming. The project explicitly does not provide arbitrary SQL, Shell, file system, or dynamic code execution tools. ## MCP Server - Entrance: `/mcp` - Transport: Streamable HTTP - Protected Resource Metadata: `/.well-known/oauth-protected-resource/mcp` First-version Tools: - `system.info` - `project.list` - `project.get` - `project.create` - `project.update` - `project.remove` - `audit.list` The first version also provides read-only Resource `web-starter://system/info` and Prompt `project.summary`. Each entrance explicitly maps permission codes and writes MCP call logs; Project write operations also enter general operation audit. V2 Agent calls `project.create`, `project.update`, `project.remove` should provide 16–128 characters of `idempotencyKey`. The same Caller, Tool, Key, and parameter security retry returns the first result; the same Key with different parameters returns stable conflict errors. For compatibility with V1, the transition period still accepts calls without Key, but such calls have no retry deduplication guarantee. Database and audit only save SHA-256 digest of Key, not plaintext Key. ## Extension When adding new modules, use `web-starter-project` as a template and follow [Module Replication Specification](docs/module-copy-guide.md). Database structure can only evolve through new Flyway migration; applied migration must not be modified. ## More Documents - [Contribution Guide](CONTRIBUTING.md) - [Security Policy](SECURITY.md) - [Overall Architecture](docs/architecture.md) - [V1 Acceptance Baseline](docs/acceptance/v1-acceptance-baseline.md) - [V1 Acceptance Evidence Template](docs/acceptance/v1-evidence-template.md) - [V1 Acceptance Record (2026-07-19)](docs/acceptance/v1-acceptance-2026-07-19.md) - [V2 Acceptance Baseline](docs/acceptance/v2-acceptance-baseline.md) - [V2 Acceptance Evidence Template](docs/acceptance/v2-evidence-template.md) - [V2-AC-01 Frozen V1 Source Provenance Evidence](docs/v1-source-provenance-evidence.md) - [Fixed 9+2 Running Report Evidence](docs/acceptance/release-runtime-test-reports.md) - [V1 to V2 Compatibility Contract](docs/compatibility/v1-to-v2.md) - [First-version Architecture Decision](docs/decisions/0001-foundation.md) - [V2 Engineering Productization Decision](docs/decisions/0002-v2-productization.md) - [Design System](docs/design-system.md) - [Deployment and O&M](docs/deployment.md) - [Security Model](docs/security.md) - [Repository Policy Gate](docs/repository-policy.md) - [Supply Chain and Release Image](docs/supply-chain.md) - [Module Replication Specification](docs/module-copy-guide.md) - [Derivative Project and Generation Module Acceptance Rehearsal](docs/generator-acceptance-rehearsal.md) ## License This project is licensed under the [Apache License 2.0](LICENSE).