first commit

2025-08-23 07:30:51 +08:00
commit 60b36366d0
6 changed files with 325 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,209 @@
+# CoreStack
+
+## 项目简介
+CoreStack 是一个集成了多种服务组件的基础架构平台，为项目提供核心支持服务，包括数据库、缓存、消息队列和 基础功能 RPC 服务等功能。
+
+## 服务组件
+
+CoreStack 包含以下核心服务组件：
+
+- **Caddy**: HTTP/HTTPS 反向代理服务器，提供TLS证书自动管理
+- **MySQL**: 关系型数据库服务
+- **Redis**: 内存缓存服务
+- **NSQ**: 高可用的分布式消息队列系统（包含nsqlookupd、nsqd、nsqadmin）
+- **Connect**: 神仙盒 Connect RPC 服务，负责各种基础 RPC 功能（如账户管理）
+
+## 环境要求
+- Docker 和 Docker Compose
+
+## 快速开始
+
+### 1. 克隆项目
+```bash
+git clone https://git.0yue.com/shenxianhe/corestack.git
+cd corestack
+```
+
+### 2. 完成配置文件设置
+
+配置分为两部分：
+
+**第一部分：修改配置文件**
+1. 复制配置文件示例：
+```bash
+cp config.example.yaml config.yaml
+```
+
+2. 根据您的实际环境修改 `config.yaml` 文件中的配置项。
+
+**第二部分：域名配置（线上环境）**
+如果您是在线上环境部署，请修改 `./caddy/Caddyfile` 文件，移除所有域名中的 `.localhost` 后缀。例如：
+- 将 `nsqadmin.shenxianhe.cn.localhost` 修改为 `nsqadmin.shenxianhe.cn`
+- 将 `connect.shenxianhe.cn.localhost` 修改为 `connect.shenxianhe.cn`
+
+### 3. 启动服务
+使用 Docker Compose 一键启动所有服务：
+
+```bash
+docker compose up -d
+```
+
+查看服务状态：
+
+```bash
+docker compose ps
+```
+
+### 4. 停止服务
+```bash
+docker compose down
+```
+
+### MySQL 配置
+- 用户名：`root`
+- 密码：`123456`
+
+### Caddy 配置
+Caddy 配置文件位于 `./caddy/Caddyfile`，当前配置了两个域名代理，后续可根据需要自行扩展更多：
+- `nsqadmin.shenxianhe.cn.localhost` - 代理到 NSQ 管理界面
+- `connect.shenxianhe.cn.localhost` - 代理到 Connect 服务
+
+### site 目录用法
+`./site` 目录用于存放静态网站文件。您可以在该目录下创建多个子目录，每个子目录对应一个独立的静态网站，从而支持多个静态网站共存。
+
+**多静态网站配置示例**：
+1. 首先在 `./site` 目录下创建子目录：
+```bash
+mkdir -p ./site/app1 ./site/app2
+```
+
+2. 将不同网站的静态文件分别放入对应的子目录
+
+3. 在 `./caddy/Caddyfile` 中添加以下配置：
+```
+app1.shenxianhe.cn.localhost {
+    root * /site/app1
+    file_server
+}
+
+app2.shenxianhe.cn.localhost {
+    root * /site/app2
+    file_server
+}
+```
+
+4. 重启Caddy服务后，即可通过 `https://app1.shenxianhe.cn.localhost` 和 `https://app2.shenxianhe.cn.localhost` 分别访问两个静态网站。
+
+## 访问服务
+
+### NSQ 管理界面
+访问地址：[https://nsqadmin.shenxianhe.cn.localhost](https://nsqadmin.shenxianhe.cn.localhost)
+- 用户名：`sky`
+- 密码：`hiccup`
+
+> **安全提示**：使用默认账户密码是不安全的行为，建议部署后立即修改密码。请参考[安全注意事项](#安全注意事项)章节。
+
+### Connect 服务
+访问地址：[https://connect.shenxianhe.cn.localhost](https://connect.shenxianhe.cn.localhost)
+
+> 注意：
+> - 如果是本地部署，请将域名添加到 `/etc/hosts` 文件中，格式为 `127.0.0.1 域名`（例如 `127.0.0.1 nsqadmin.shenxianhe.cn.localhost`）
+
+## HTTPS 证书配置
+
+当使用 Docker 进行本地开发并启用 HTTPS 时，Caddy 会使用本地 CA 颁发证书。外部 HTTP 客户端默认不会信任这些证书。要解决这个问题，您可以在主机的信任存储中安装 Caddy 的根 CA 证书：
+
+### Linux
+```bash
+docker compose cp \
+ caddy:/data/caddy/pki/authorities/local/root.crt \
+ /usr/local/share/ca-certificates/root.crt \
+ && sudo update-ca-certificates
+```
+
+### macOS
+```bash
+docker compose cp \
+ caddy:/data/caddy/pki/authorities/local/root.crt \
+ /tmp/root.crt \
+ && sudo security add-trusted-cert -d -r trustRoot \
+ -k /Library/Keychains/System.keychain /tmp/root.crt
+```
+
+### Windows
+```bash
+docker compose cp \
+ caddy:/data/caddy/pki/authorities/local/root.crt \
+ %TEMP%/root.crt \
+ && certutil -addstore -f "ROOT" %TEMP%/root.crt
+```
+
+## 常见问题
+
+### 服务启动失败
+如果服务启动失败，请检查：
+1. Docker 是否正常运行
+2. 端口是否被占用
+3. 查看日志获取详细错误信息：`docker compose logs <服务名称>`
+
+### 如何重置 MySQL 数据
+**警告：此操作会永久删除所有数据库数据，请谨慎操作！**
+
+方法一：使用 -v 参数删除所有数据卷（包括MySQL、Caddy等）
+```bash
+docker compose down -v
+# 重新启动服务后会自动创建空的数据卷
+docker compose up -d
+```
+
+方法二：仅删除MySQL数据卷（保留其他数据卷）
+```bash
+docker compose down
+# 列出所有数据卷，找到MySQL数据卷名称（通常为 corestack_mysql）
+docker volume ls
+# 删除MySQL数据卷
+docker volume rm corestack_mysql
+# 重新启动服务后会自动创建空的MySQL数据卷
+docker compose up -d
+```
+
+## 安全注意事项
+
+### 修改NSQ管理界面的默认密码
+当前Caddyfile中配置了NSQ管理界面的默认用户名和密码，这在生产环境中是不安全的。请按照以下步骤修改密码：
+
+1. 使用Caddy提供的`hash-password`命令生成密码哈希：
+```bash
+docker run --rm caddy:2.10.0 hash-password -plaintext "your-new-password"
+```
+
+2. 将生成的哈希值复制下来
+
+3. 编辑`./caddy/Caddyfile`文件，替换`basic_auth`部分的密码哈希：
+```
+nsqadmin.shenxianhe.cn {
+    basic_auth {
+        # 修改为您的用户名和新的密码哈希
+        your-username $2a$14$...（生成的哈希值）
+    }
+    reverse_proxy nsqadmin:4171
+}
+```
+
+4. 重启Caddy服务：
+```bash
+docker compose restart caddy
+```
+
+
+## 维护与更新
+
+更新服务镜像：
+```bash
+docker compose pull
+```
+
+重新构建并启动服务：
+```bash
+docker compose up -d --build
+```