口袋水晶攻略

口袋水晶本地部署及核心功能快速上手实操全攻略

一、前置准备

1.1 环境要求

必须安装以下指定版本工具：JDK 1.8（推荐8u291及以上）、Maven 3.5+、MySQL 5.7+（或8.0+）。所有工具需配置系统环境变量，在命令行执行java -version、mvn -v、mysql -V验证安装成功。

二、快速部署步骤

2.1 获取源码包

直接访问https://github.com/weibocom/pocket-crystal/archive/refs/tags/v1.2.0.zip下载稳定版源码，解压到本地目录，路径禁止包含中文、空格或特殊字符（如D:\pocket-crystal）。

2.2 配置数据库

1. 登录MySQL执行建库命令：```CREATE DATABASE pocket_crystal CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;```；2. 进入解压后源码的core模块，找到src/main/resources/application.properties，替换为以下完整配置：

``` server.port=8080 spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver spring.datasource.url=jdbc:mysql://localhost:3306/pocket_crystal?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai spring.datasource.username=root spring.datasource.password=你的MySQL root密码 spring.jpa.hibernate.ddl-auto=update ```

必须提前创建数据库，否则服务启动时会因表不存在报错；MySQL8.0+无需修改驱动类，以上配置通用。

2.3 构建项目

命令行cd到源码根目录，执行Maven构建命令：

``` mvn clean package -DskipTests ```

必须用JDK 1.8执行该命令，JDK11及以上会编译失败；构建完成后，core/target目录生成可执行jar包：pocket-crystal-core-1.2.0.jar。

2.4 启动核心服务

命令行执行启动命令：

``` java -jar core/target/pocket-crystal-core-1.2.0.jar ```

启动成功后，控制台输出日志“Started PocketCrystalApplication in X.XXX seconds”；若未出现该日志，检查8080端口是否被占用，用对应系统命令杀进程重启（Windows：netstat -ano | findstr :8080 → taskkill /F /PID 进程ID；Linux：lsof -i:8080 → kill -9 PID）。

三、初始配置与功能验证

3.1 登录后台管理

浏览器访问http://localhost:8080，默认账号admin，密码admin；首次登录必须立即修改密码（6-20位，含字母+数字），否则无法操作。

3.2 创建配置分组

1. 左侧菜单【配置管理】→【分组管理】；2. 点击右上角【新增分组】；3. 分组ID填test-group，名称填“测试分组”；4. 点击【确定】。分组ID仅支持字母、数字、下划线，禁止特殊字符或中文，否则客户端无法识别。

3.3 新增配置项

1. 进入【配置管理】→【配置列表】；2. 顶部下拉选test-group；3. 点击【新增配置】；4. Key填test.key，Value填“Hello Pocket Crystal”，备注填“入门测试”；5. 点击【保存】。同一分组内配置Key必须唯一，重复会保存失败。

3.4 客户端获取配置验证

新建Maven项目，在pom.xml添加客户端依赖：

```xml com.weibo.pocket.crystal pocket-crystal-client 1.2.0 ```

新建Java类TestClient，复制以下代码：

```java import com.weibo.pocket.crystal.client.PocketCrystalClient; public class TestClient { public static void main(String[] args) { // 初始化客户端：参数1=后台地址，参数2=账号，参数3=新密码 PocketCrystalClient client = new PocketCrystalClient("http://localhost:8080", "admin", "你的新密码"); // 获取配置：参数1=分组ID，参数2=配置Key String configValue = client.getProperty("test-group", "test.key"); System.out.println("获取到的配置值：" + configValue); } } ```

执行main方法，控制台输出“获取到的配置值：Hello Pocket Crystal”则验证完成；若报错，检查分组ID、Key拼写或客户端权限。

四、常见问题快速排查

4.1 服务启动失败，端口被占用

按2.4小节命令杀进程后重启，禁止直接修改端口，需在application.properties改server.port并同步修改客户端地址。

4.2 数据库连接失败

检查MySQL是否启动、数据库名是否正确、配置文件的用户名/密码是否匹配；确保URL时区为Asia/Shanghai，否则会触发时区错误。

4.3 配置获取权限错误

后台【权限管理】将客户端账号（如admin）加入对应分组权限列表；测试阶段直接用admin账号即可，默认拥有所有权限。